Crate tracing_ecs

source ·
Expand description

Tracing subscriber that outputs json log lines compatible with ECS (Elastic Common Schema).

More specifically, this crate provides a Layer implementation that can be composed with an existing Subscriber from the tracing-subscribers crate.

See how is implemented the install method to understand what’s done under the hood.

§How spans are handled

All spans attributes are directly appended to the final json object.

As a result, there might be duplicate keys in the resulting json if static extra fields have the same keys as some span attributes, or if an attribute is named message (which shall be reserved to the logged event).

This behavior can be customized by implementing the AttributeMapper trait.

§JSON Normalization

Output is normalized by default so there is no dot anymore in the resulting json keys. See https://www.elastic.co/guide/en/ecs/current/ecs-guidelines.html

See ECSLayerBuilder.normalize_json

§Examples

Install a default subscriber that outputs json to stdout:

use tracing_ecs::ECSLayerBuilder;

ECSLayerBuilder::default()
    .stdout()
    .install()
    .unwrap()

Install a subscriber with custom extra fields that outputs json to stdout (here we use the json! macro but it accepts anything that serializes to a json map):

use serde_json::json;
use tracing_ecs::ECSLayerBuilder;

ECSLayerBuilder::default()
    .with_extra_fields(json!({
        "labels": {
            "env": "prod",
        },
        "tags": ["service", "foobar"]
    }))
    .unwrap()
    .stdout()
    .install()
    .unwrap();

With attributes name mapping:

use tracing_ecs::ECSLayerBuilder;
use std::borrow::Cow;
use std::ops::Deref;

ECSLayerBuilder::default()
 .with_attribute_mapper(
    |_span_name: &str, name: Cow<'static, str>| match name.deref() {
        "txid" => "transaction.id".into(),
        _ => name,
    },
 ).stdout().install().unwrap()

Structs§

  • ECSLayer
    The final Layer object to be used in a tracing-subscriber layered subscriber.
  • ECSLayerBuilder
    Builder for a subscriber Layer writing ECS compatible json lines to a writer.

Enums§

Constants§

  • EVENT_SPAN_NAME
    This span_name is used when calling the current AttributeMapper while processing event attributes.

Traits§