Get started
editGet started
editStep 1: Install
editAdd the package to your go.mod
file:
require go.elastic.co/ecslogrus master
Step 2: Configure
editSet up a default logger. For example:
log := logrus.New() log.SetFormatter(&ecslogrus.Formatter{})
Examples
editUse structured logging
edit// Add custom fields. log.WithError(errors.New("boom!")).WithField("custom", "foo").Info("hello")
The example above produces the following log output:
{ "@timestamp": "2021-01-20T11:12:43.061+0800", "custom":"foo", "ecs.version": "1.6.0", "error": { "message": "boom!" }, "log.level": "info", "message":"hello" }
Nest custom fields under "labels"
editFor complete ECS compliance, custom fields should be nested in a "labels" object.
log := logrus.New() log.SetFormatter(&ecslogrus.Formatter{ DataKey: "labels", }) log.WithError(errors.New("boom!")).WithField("custom", "foo").Info("hello")
The example above produces the following log output:
{ "@timestamp": "2021-01-20T11:12:43.061+0800", "ecs.version": "1.6.0", "error": { "message": "boom!" }, "labels": { "custom": "foo" }, "log.level": "info", "message":"hello" }
Report caller information
editlog := logrus.New() log.SetFormatter(&ecslogrus.Formatter{}) log.ReportCaller = true log.Info("hello")
The example above produces the following log output:
{ "@timestamp": "2021-01-20T11:12:43.061+0800", "ecs.version": "1.6.0", "log.level": "info", "log.origin.file.line": 48, "log.origin.file.name": "/path/to/example_test.go", "log.origin.function": "go.elastic.co/ecslogrus_test.ExampleFoo", "message":"hello" }
Step 3: Configure Filebeat
edit- Follow the Filebeat quick start
-
Add the following configuration to your
filebeat.yaml
file.
For Filebeat 7.16+
filebeat.yaml.
filebeat.inputs: - type: filestream paths: /path/to/logs.json parsers: - ndjson: overwrite_keys: true add_error_key: true expand_keys: true processors: - add_host_metadata: ~ - add_cloud_metadata: ~ - add_docker_metadata: ~ - add_kubernetes_metadata: ~
Use the filestream input to read lines from active log files. |
|
Values from the decoded JSON object overwrite the fields that Filebeat normally adds (type, source, offset, etc.) in case of conflicts. |
|
Filebeat adds an "error.message" and "error.type: json" key in case of JSON unmarshalling errors. |
|
Filebeat will recursively de-dot keys in the decoded JSON, and expand them into a hierarchical object structure. |
|
Processors enhance your data. See processors to learn more. |
For Filebeat < 7.16
filebeat.yaml.
filebeat.inputs: - type: log paths: /path/to/logs.json json.keys_under_root: true json.overwrite_keys: true json.add_error_key: true json.expand_keys: true processors: - add_host_metadata: ~ - add_cloud_metadata: ~ - add_docker_metadata: ~ - add_kubernetes_metadata: ~
- Make sure your application logs to stdout/stderr.
- Follow the Run Filebeat on Kubernetes guide.
-
Enable hints-based autodiscover (uncomment the corresponding section in
filebeat-kubernetes.yaml
). - Add these annotations to your pods that log using ECS loggers. This will make sure the logs are parsed appropriately.
annotations: co.elastic.logs/json.overwrite_keys: true co.elastic.logs/json.add_error_key: true co.elastic.logs/json.expand_keys: true
Values from the decoded JSON object overwrite the fields that Filebeat normally adds (type, source, offset, etc.) in case of conflicts. |
|
Filebeat adds an "error.message" and "error.type: json" key in case of JSON unmarshalling errors. |
|
Filebeat will recursively de-dot keys in the decoded JSON, and expand them into a hierarchical object structure. |
- Make sure your application logs to stdout/stderr.
- Follow the Run Filebeat on Docker guide.
- Enable hints-based autodiscover.
- Add these labels to your containers that log using ECS loggers. This will make sure the logs are parsed appropriately.
docker-compose.yml.
labels: co.elastic.logs/json.overwrite_keys: true co.elastic.logs/json.add_error_key: true co.elastic.logs/json.expand_keys: true
Values from the decoded JSON object overwrite the fields that Filebeat normally adds (type, source, offset, etc.) in case of conflicts. |
|
Filebeat adds an "error.message" and "error.type: json" key in case of JSON unmarshalling errors. |
|
Filebeat will recursively de-dot keys in the decoded JSON, and expand them into a hierarchical object structure. |
For more information, see the Filebeat reference.