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