1---
2last_modified_on: "2020-07-13"
3delivery_guarantee: "at_least_once"
4component_title: "File"
5description: "The Vector `file` sink streams `log` events to a file."
6event_types: ["log"]
7function_category: "transmit"
8issues_url: https://github.com/timberio/vector/issues?q=is%3Aopen+is%3Aissue+label%3A%22sink%3A+file%22
9operating_systems: ["Linux","MacOS","Windows"]
10sidebar_label: "file|[\"log\"]"
11source_url: https://github.com/timberio/vector/tree/master/src/sinks/file
12status: "prod-ready"
13title: "File Sink"
14unsupported_operating_systems: []
15---
16
17import Fields from '@site/src/components/Fields';
18import Field from '@site/src/components/Field';
19import Tabs from '@theme/Tabs';
20import TabItem from '@theme/TabItem';
21
22The Vector `file` sink
23[streams](#streaming) [`log`][docs.data-model.log] events to a file.
24
25<!--
26     THIS FILE IS AUTOGENERATED!
27
28     To make changes please edit the template located at:
29
30     website/docs/reference/sinks/file.md.erb
31-->
32
33## Configuration
34
35<Tabs
36  block={true}
37  defaultValue="common"
38  values={[{"label":"Common","value":"common"},{"label":"Advanced","value":"advanced"}]}>
39<TabItem value="common">
40
41```toml title="vector.toml"
42[sinks.my_sink_id]
43  # General
44  type = "file" # required
45  inputs = ["my-source-or-transform-id"] # required
46  healthcheck = true # optional, default
47  path = "vector-%Y-%m-%d.log" # required
48
49  # Encoding
50  encoding.codec = "ndjson" # required
51```
52
53</TabItem>
54<TabItem value="advanced">
55
56```toml title="vector.toml"
57[sinks.my_sink_id]
58  # General
59  type = "file" # required
60  inputs = ["my-source-or-transform-id"] # required
61  healthcheck = true # optional, default
62  idle_timeout_secs = "30" # optional, default
63  path = "vector-%Y-%m-%d.log" # required
64
65  # Encoding
66  encoding.codec = "ndjson" # required
67  encoding.except_fields = ["timestamp", "message", "host"] # optional, no default
68  encoding.only_fields = ["timestamp", "message", "host"] # optional, no default
69  encoding.timestamp_format = "rfc3339" # optional, default
70```
71
72</TabItem>
73</Tabs>
74
75<Fields filters={true}>
76<Field
77  common={true}
78  defaultValue={null}
79  enumValues={null}
80  examples={[]}
81  groups={[]}
82  name={"encoding"}
83  path={null}
84  relevantWhen={null}
85  required={true}
86  templateable={false}
87  type={"table"}
88  unit={null}
89  warnings={[]}
90  >
91
92### encoding
93
94Configures the encoding specific sink behavior.
95
96
97<Fields filters={false}>
98<Field
99  common={true}
100  defaultValue={null}
101  enumValues={{"ndjson":"Each event is encoded into JSON and the payload is new line delimited.","text":"Each event is encoded into text via the `message` key and the payload is new line delimited."}}
102  examples={["ndjson","text"]}
103  groups={[]}
104  name={"codec"}
105  path={"encoding"}
106  relevantWhen={null}
107  required={true}
108  templateable={false}
109  type={"string"}
110  unit={null}
111  warnings={[]}
112  >
113
114#### codec
115
116The encoding codec used to serialize the events before outputting.
117
118
119
120</Field>
121<Field
122  common={false}
123  defaultValue={null}
124  enumValues={null}
125  examples={[["timestamp","message","host"]]}
126  groups={[]}
127  name={"except_fields"}
128  path={"encoding"}
129  relevantWhen={null}
130  required={false}
131  templateable={false}
132  type={"[string]"}
133  unit={null}
134  warnings={[]}
135  >
136
137#### except_fields
138
139Prevent the sink from encoding the specified labels.
140
141
142
143</Field>
144<Field
145  common={false}
146  defaultValue={null}
147  enumValues={null}
148  examples={[["timestamp","message","host"]]}
149  groups={[]}
150  name={"only_fields"}
151  path={"encoding"}
152  relevantWhen={null}
153  required={false}
154  templateable={false}
155  type={"[string]"}
156  unit={null}
157  warnings={[]}
158  >
159
160#### only_fields
161
162Limit the sink to only encoding the specified labels.
163
164
165
166</Field>
167<Field
168  common={false}
169  defaultValue={"rfc3339"}
170  enumValues={{"rfc3339":"Format as an RFC3339 string","unix":"Format as a unix timestamp, can be parsed as a Clickhouse DateTime"}}
171  examples={["rfc3339","unix"]}
172  groups={[]}
173  name={"timestamp_format"}
174  path={"encoding"}
175  relevantWhen={null}
176  required={false}
177  templateable={false}
178  type={"string"}
179  unit={null}
180  warnings={[]}
181  >
182
183#### timestamp_format
184
185How to format event timestamps.
186
187
188
189</Field>
190</Fields>
191
192</Field>
193<Field
194  common={true}
195  defaultValue={true}
196  enumValues={null}
197  examples={[true,false]}
198  groups={[]}
199  name={"healthcheck"}
200  path={null}
201  relevantWhen={null}
202  required={false}
203  templateable={false}
204  type={"bool"}
205  unit={null}
206  warnings={[]}
207  >
208
209### healthcheck
210
211Enables/disables the sink healthcheck upon start.
212
213
214
215</Field>
216<Field
217  common={false}
218  defaultValue={"30"}
219  enumValues={null}
220  examples={["30"]}
221  groups={[]}
222  name={"idle_timeout_secs"}
223  path={null}
224  relevantWhen={null}
225  required={false}
226  templateable={false}
227  type={"uint"}
228  unit={null}
229  warnings={[]}
230  >
231
232### idle_timeout_secs
233
234The amount of time a file can be idle  and stay open. After not receiving any
235events for this timeout, the file will be flushed and closed.
236
237
238
239</Field>
240<Field
241  common={true}
242  defaultValue={null}
243  enumValues={null}
244  examples={["vector-%Y-%m-%d.log","application-{{ application_id }}-%Y-%m-%d.log"]}
245  groups={[]}
246  name={"path"}
247  path={null}
248  relevantWhen={null}
249  required={true}
250  templateable={true}
251  type={"string"}
252  unit={null}
253  warnings={[]}
254  >
255
256### path
257
258File name to write events to.
259 See [Template Syntax](#template-syntax) for more info.
260
261
262</Field>
263</Fields>
264
265
266## How It Works
267
268### Dynamic File And Directory Creation
269
270Vector will attempt to create the entire directory structure and the file when
271emitting events to the file sink. This requires that the Vector agent have
272the correct permissions to create and write to files in the specified directories.
273
274### Environment Variables
275
276Environment variables are supported through all of Vector's configuration.
277Simply add `${MY_ENV_VAR}` in your Vector configuration file and the variable
278will be replaced before being evaluated.
279
280You can learn more in the
281[Environment Variables][docs.configuration#environment-variables] section.
282
283### Streaming
284
285The `file` sink streams data on a real-time
286event-by-event basis. It does not batch data.
287
288### Template Syntax
289
290The [`path`](#path) options
291support [Vector's template syntax][docs.reference.templating], enabling dynamic
292values derived from the event's data. This syntax accepts
293[strptime specifiers][urls.strptime_specifiers] as well as the
294`{{ field_name }}` syntax for accessing event fields. For example:
295
296```toml title="vector.toml"
297[sinks.my_file_sink_id]
298  # ...
299  path = "vector-%Y-%m-%d.log"
300  path = "application-{{ application_id }}-%Y-%m-%d.log"
301  # ...
302```
303
304You can learn more about the complete syntax in the
305[templating reference][docs.reference.templating].
306
307[docs.configuration#environment-variables]: /docs/setup/configuration/#environment-variables
308[docs.data-model.log]: /docs/about/data-model/log/
309[docs.reference.templating]: /docs/reference/templating/
310[urls.strptime_specifiers]: https://docs.rs/chrono/0.4.11/chrono/format/strftime/index.html#specifiers
311