Skip to main content

Crate emit_opentelemetry

Crate emit_opentelemetry 

Source
Expand description

Integrate emit with the OpenTelemetry SDK.

This library forwards diagnostic events from emit through the OpenTelemetry SDK as log records and spans. This library is for applications that already use the OpenTelemetry SDK. It’s also intended for applications that need to unify multiple instrumentation libraries, like emit, log, and tracing, into a shared pipeline. If you’d just like to send emit diagnostics via OTLP to the OpenTelemetry Collector or other compatible service, then consider emit_otlp.

emit_opentelemetry version x.y.z is compatible with opentelemetry_sdk version x.y.*.

§Getting started

Configure the OpenTelemetry SDK as per its documentation, then add emit and emit_opentelemetry to your Cargo.toml:

[dependencies.emit]
version = "1"

# add `emit_opentelemetry` with the same major/minor as the OpenTelemetry SDK
[dependencies.emit_opentelemetry]
version = "0.31"

[dependencies.opentelemetry_sdk]
version = "0.31"
features = ["trace", "logs"]

[dependencies.opentelemetry]
version = "0.31"
features = ["trace", "logs"]

Initialize emit to send diagnostics to the OpenTelemetry SDK using setup:

fn main() {
    // Configure the OpenTelemetry SDK
    // See the OpenTelemetry SDK docs for details on configuration
    let logger_provider = opentelemetry_sdk::logs::SdkLoggerProvider::builder()
        .with_simple_exporter(opentelemetry_stdout::LogExporter::default())
        .build();

    let tracer_provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_simple_exporter(opentelemetry_stdout::SpanExporter::default())
        .build();

    // Configure `emit` to point to the OpenTelemetry SDK
    let rt = emit_opentelemetry::setup(logger_provider, tracer_provider).init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(30));

    // Shutdown the OpenTelemetry SDK
}

Diagnostic events produced by the emit::span macro are sent to an opentelemetry::trace::Tracer as an opentelemetry::trace::Span on completion. All other emitted events are sent to an opentelemetry::logs::Logger as opentelemetry::logs::LogRecords.

§Span lifecycle

Spans created by emit’s #[emit::span] attribute will be created through the configured opentelemetry::trace::TracerProvider. The following well-known emit properties are interpreted during span creation:

  • span_id: Sets the id of the span. If the id matches the current span then no new span will be created.
  • trace_id: Sets the trace id of the span. Otherwise the current trace id will be used.
  • span_name: Sets the name of the span. Otherwise a default name derived from the span’s message template will be used.
  • span_kind: Sets the kind of the span. Otherwise the default kind of internal will be used.
  • span_links: Populates a set of links on the span.

Spans created through emit don’t carry additional attributes on them until completion.

Spans are completed either by emitting an event manually, or when the function annotated with #[emit::span] completes. At this point if the event is a span, and its context matches the current OpenTelemetry span context, it’ll be emitted as a span. Otherwise it’ll be emitted as a regular log event. The following well-known emit properties are interpreted during span completion:

  • err: Mapped onto the semantic exception event on the span, and the span’s status will be set to Error.
  • lvl: If its value is error, the span’s status will be set to Error.

If the span doesn’t have a meaningful name configured already, then the rendered message will be used.

§Sampling

By default, emit events will be excluded if they are inside an unsampled OpenTelemetry trace, even if that trace is marked as recorded. OpenTelemetry will still propagate sampling decisions, but emit’s own spans will not be constructed within the unsampled trace.

You can change this behavior by overriding the filter using emit::Setup::emit_when on the value returned by setup.

emit doesn’t track trace flags, trace state, or whether links are remote in its model. This information will be populated from the current span context.

§Span parents

When using emit_opentelemetry, any SpanCtxt pulled from ambient context won’t carry a parent span id, even for non-root spans. This is because the OpenTelemetry SDK doesn’t have an API for accessing the parent-child relationship of a span after its construction.

§Limitations

This library doesn’t support emit’s metrics as OpenTelemetry metrics. Any metric samples produced by emit will be emitted as log records.

Spans produced manually (without adding their trace ids and span ids to the shared emit::Ctxt) will be emitted as log events instead of as spans.

§Troubleshooting

If you’re not seeing emit diagnostics flow as expected through the OpenTelemetry SDK, you can try configuring emit’s internal logger, and collect metrics from the integration:

use emit::metric::Source;

fn main() {
    let logger_provider = opentelemetry_sdk::logs::SdkLoggerProvider::builder()
        .with_simple_exporter(opentelemetry_stdout::LogExporter::default())
        .build();

    let tracer_provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_simple_exporter(opentelemetry_stdout::SpanExporter::default())
        .build();

    // 1. Initialize the internal logger
    //    Diagnostics produced by `emit_opentelemetry` itself will go here
    let internal = emit::setup()
        .emit_to(emit_term::stdout())
        .init_internal();

    let mut reporter = emit::metric::Reporter::new();

    let rt = emit_opentelemetry::setup(logger_provider, tracer_provider)
        .map_emitter(|emitter| {
            // 2. Add `emit_opentelemetry`'s metrics to a reporter so we can see what it's up to
            //    You can do this independently of the internal emitter
            reporter.add_source(emitter.metric_source());

            emitter
        })
        .init();

    // Your app code goes here

    rt.blocking_flush(std::time::Duration::from_secs(30));

    // 3. Report metrics after attempting to flush
    //    You could also do this periodically as your application runs
    reporter.emit_metrics(&internal.emitter());
}

Also see the opentelemetry docs for any details on getting diagnostics out of it.

Structs§

EmitOpenTelemetryMetrics
Metrics produced by the emit to the OpenTelemetry SDK integration itself.
OpenTelemetryCtxt
An emit::Ctxt created during setup for integrating emit with the OpenTelemetry SDK.
OpenTelemetryEmitter
An emit::Emitter creating during setup for integrating emit with the OpenTelemetry SDK.
OpenTelemetryFrame
The emit::Ctxt::Frame used by OpenTelemetryCtxt.
OpenTelemetryIsSampledFilter
A filter that excludes span events inside an unsampled trace.
OpenTelemetryProps
The emit::Ctxt::Current used by OpenTelemetryCtxt.

Functions§

setup
Start a builder for the emit to OpenTelemetry SDK integration.