Skip to main content

Crate grow_datadog_apm

Crate grow_datadog_apm 

Source
Expand description

§grow-datadog-apm

Rust SDK for Datadog APM by Grow Codes.

Two halves:

  • Tracing to the local Datadog Agent: init_tracing (OpenTelemetry, OTLP to the Agent, unified service tagging, DatadogPropagator, Datadog error attributes), the id helpers (to_datadog_trace_id, …) and log correlation (datadog_log_fields). The client’s health, ping and server_version use the Agent’s GET /info.
  • Query via the Datadog SaaS API: DatadogSpansQuery (spans search, aggregate, get_trace, list_services, …; needs DD_API_KEY + DD_APP_KEY).
use grow_datadog_apm::{datadog_log_fields, tracing::{traced, TracingConfig}, DatadogApmClient};

let client = DatadogApmClient::from_env()?;
let health = client.health().await?;
println!("healthy: {}", health.healthy);
let tracing = client.init_tracing(TracingConfig::new("checkout"))?;
traced("charge-card", async {
    println!("{:?}", datadog_log_fields(Default::default()));
    Ok::<_, std::io::Error>(())
})
.await
.ok();
client.close().await; // flushes the spans

Features: blocking (a blocking client), testing (in-memory fakes and the conformance runner) , tower and reqwest-middleware (tracing instrumentation) .

Re-exports§

pub use crate::core::Error;
pub use crate::core::ErrorCode;
pub use crate::core::HealthStatus;
pub use crate::core::Result;
pub use crate::core::RetryPolicy;
pub use crate::core::Secret;

Modules§

aggregation
Aggregation functions of the spans aggregate API.
blockingblocking
Blocking wrapper (feature blocking). Each client owns a tokio runtime with one worker thread, so background work (exports, retries’ timers) keeps running between blocking calls.
core
Shared core: errors, configuration, secrets in config, redaction, retries and transport.
testingtesting
Test support (feature testing): in-memory fakes and the conformance runner (SPEC §6).
tracing
Tracing category (SPEC §5), built on the OpenTelemetry SDK: setup, span helpers, propagation, framework adapters and the trace query model.

Structs§

AgentInfo
The Agent’s GET /info document (fields this package reads).
AggregateSpansOptions
Filter of DatadogSpansQuery::aggregate_spans.
DatadogApmClient
Async client for Datadog APM. Cheap to clone (clones share one connection pool).
DatadogApmConfig
Immutable client configuration; build it with DatadogApmConfig::builder or DatadogApmConfig::from_env. Debug output redacts every credential.
DatadogApmConfigBuilder
Builder for DatadogApmConfig. Values set here win over the environment.
DatadogLogFields
Datadog log correlation fields; serializes with the dd.* keys (absent fields omitted).
DatadogLogFieldsOptions
Explicit unified-service-tagging values for datadog_log_fields (None = not given).
DatadogPropagator
Datadog propagator: injects and extracts x-datadog-trace-id (low 64 bits, decimal), x-datadog-parent-id (decimal), x-datadog-sampling-priority (1/0) and, for 128-bit ids, x-datadog-tags: _dd.p.tid=<high 64 bits hex>.
DatadogQueryWarning
A warning attached to a partial query result.
DatadogSpan
One span returned by the spans search API.
DatadogSpanExporter
Span exporter wrapper installed by init_tracing: fills the Datadog error attributes (with_datadog_error_attributes) and adds the terminated-context links (with_terminated_context_link) before handing the spans to the wrapped exporter. It covers with_span, traced, the HTTP adapters and plain OpenTelemetry calls (the Rust SDK has no span processor hook that may still change an ending span).
DatadogSpansPage
One page of DatadogSpansQuery::search_spans_page.
DatadogSpansQuery
The Datadog spans query client (SaaS API at https://api.<site>, headers DD-API-KEY and DD-APPLICATION-KEY). It implements TraceQueryClient on top of the spans search and aggregate APIs, plus the Datadog-specific search_spans, aggregate_spans and ping. Cheap to clone.
DatadogTraceId
A trace id split the way Datadog stores it.
DatadogTracingHandle
A running Datadog tracing setup. Dereferences to the generic TracingHandle (tracer, tracer_provider, force_flush, shutdown, …). Cheap to clone.
GetTraceOptions
Options of DatadogSpansQuery::get_trace_with_options.
InitTracingOptions
Extra options of init_tracing_with_options.
ListServicesOptions
Options of DatadogSpansQuery::list_services_with_options.
SearchSpansOptions
Options of DatadogSpansQuery::search_spans and search_spans_page.
SpanAggregateBucket
One bucket of an aggregation.
SpanAggregateResult
Result of DatadogSpansQuery::aggregate_spans.
SpanCompute
One computation of DatadogSpansQuery::aggregate_spans.
SpanGroupBy
One group-by facet of DatadogSpansQuery::aggregate_spans.
SpanGroupBySort
Order of the groups of a SpanGroupBy.
SpanHistogram
Buckets a numeric facet.
SpanTimeseriesPoint
A point of a timeseries compute.
TerminatedContext
A W3C context that lost against Datadog headers in DatadogPropagator’s extract.

Enums§

DatadogTime
A point in time for a query: an absolute time or a Datadog date expression (now-15m, ISO-8601, epoch milliseconds).
SpanComputeValue
One compute result of a bucket.

Constants§

AGENT_TRACE_PORT
Default Agent trace intake port (GET /info).
ATTR_ERROR_MESSAGE
The error.message span attribute.
ATTR_ERROR_STACK
The error.stack span attribute.
ATTR_ERROR_TYPE
The error.type span attribute (error type name).
DATADOG_DEFAULT_PROPAGATORS
The default propagators of this package: Datadog headers, W3C trace context and baggage.
DATADOG_ORIGIN_HEADER
Origin of the trace (synthetics, rum, …).
DATADOG_PARENT_ID_HEADER
Carries the span id, unsigned decimal.
DATADOG_SAMPLING_PRIORITY_HEADER
1 (sampled) or 0 (not sampled).
DATADOG_SITES
The Datadog sites of the official OpenAPI spec (servers enum). Other host names are accepted too (the spec’s “any Datadog deployment” server), but never a scheme, port or path.
DATADOG_TAGS_HEADER
Propagated tags, e.g. _dd.p.tid=<high 64 bits hex>.
DATADOG_TRACE_ID_HEADER
Carries the low 64 bits of the trace id, unsigned decimal.
DATADOG_WAIT_INTERVAL
Default polling interval of DatadogSpansQuery’s wait_for_trace (Datadog allows 50 searches per minute).
DEFAULT_PROTOCOL
Default OTLP protocol of this package.
DEFAULT_SITE
Default Datadog site (US1).
DEFAULT_URL
Default Datadog Agent trace intake URL (health, ping and server_version use its GET /info).
LOG_FIELD_ENV
Key of DatadogLogFields::env.
LOG_FIELD_SERVICE
Key of DatadogLogFields::service.
LOG_FIELD_SPAN_ID
Key of DatadogLogFields::span_id.
LOG_FIELD_TRACE_ID
Key of DatadogLogFields::trace_id.
LOG_FIELD_VERSION
Key of DatadogLogFields::version.
OTLP_GRPC_PORT
Default Agent OTLP/gRPC port.
OTLP_HTTP_PORT
Default Agent OTLP/HTTP port.
PROPAGATOR_DATADOG
Propagator name of DatadogPropagator in TracingConfig::propagators (PropagatorKind::Other("datadog")).

Functions§

api_url_for_site
The API base URL of a site: https://api.<site>. An empty site means DEFAULT_SITE.
datadog_error_attributes
The Datadog error attributes for err: error.type (the Rust type name of E), error.message (err.to_string()) and error.stack (a backtrace of the caller; Rust errors carry no stack).
datadog_exporter_factory
The exporter factory of this package: OTLP http/protobuf or grpc to config.endpoint (default: the local Agent), wrapped in a DatadogSpanExporter. native is a CONFIG error (the package exports OTLP only).
datadog_kind
Converts a Datadog span.kind (or OpenTelemetry kind name) to a SpanKind; unknown values are Unspecified.
datadog_log_fields
The Datadog log correlation fields for the active span, ready to merge into any structured log record: dd.trace_id, dd.span_id, dd.service, dd.env, dd.version. Service, env and version come from options, else the last init_tracing config (or set_datadog_log_defaults). Without a valid span only the service fields are set; unknown fields are None.
datadog_search_span_to_span
Maps one span of the spans search API (data[i] of POST /api/v2/spans/events/search, or its attributes) to a SPEC Span. Nested span attributes (attributes, custom) are flattened to dotted keys; tags (key:value) are added as attributes. Name = resource_name, kind from span.kind, status error when status is error or error is set; duration from the duration attribute (nanoseconds) when present, else end − start.
datadog_trace_id_string
The trace id in the format Datadog’s log correlation (dd.trace_id) and its search API use: 32 lower-case hex characters for a 128-bit id, the low 64 bits in decimal for a 64-bit id.
datadog_trace_span_to_span
Maps a Datadog trace span — the Agent’s format (trace_id, span_id, parent_id, start, duration, meta, metrics) or the trace-by-id API format (traceID, traceIDFull, spanID, parentID, startTime, endTime, duration) — to a SPEC Span.
extract_datadog_context
Reads the Datadog headers of a carrier into a remote span context; None when they are missing or invalid. A missing sampling priority counts as sampled.
from_datadog_span_id
Converts a Datadog unsigned decimal span id to 16 lower-case hex characters.
from_datadog_trace_id
Joins a Datadog trace id (low 64 bits in decimal, optional _dd.p.tid high half in hex) into a 32-character OpenTelemetry trace id. None (or an empty string) means a zero high half.
init_tracing
Sets up OpenTelemetry tracing that exports to the Datadog Agent (SPEC §5):
init_tracing_with_options
init_tracing with an explicit DatadogApmConfig or environment.
is_datadog_site
Whether site is one of DATADOG_SITES.
normalize_datadog_span_id
Normalizes a Datadog decimal span id to 16 hex characters; None for an empty or zero id.
normalize_datadog_trace_id
Normalizes any trace id Datadog returns to 32 lower-case hex characters: a 32-character value is hex, a shorter all-digit value (at most 20 digits) is the 64-bit decimal form, anything else is hex.
normalize_site
Lower-cases and trims a site name.
order_propagators
Puts tracecontext before datadog so the Datadog propagator sees the W3C result and applies the conflict rules (Datadog wins); every other propagator keeps its position.
otlp_traces_url
The exporter URL for a protocol and an OTLP endpoint: for http/protobuf an endpoint without a path gets /v1/traces; gRPC endpoints are used as they are.
parse_datadog_tags
Parses Datadog tags (DD_TAGS): key:value pairs separated by commas and/or spaces. Entries without a : or with an empty key are ignored.
quote_query_value
Quotes a value for the Datadog query syntax when it contains spaces or special characters.
record_datadog_exception
Alias of record_exception (Go name RecordDatadogException).
record_exception
Records err as an exception event on the active span (like tracing::record_exception) and also sets the Datadog error attributes. The span status is unchanged.
set_datadog_error
Alias of set_error (Go name SetDatadogError).
set_datadog_log_defaults
Sets the service/env/version datadog_log_fields uses when none are given (init_tracing calls it with its effective config).
set_error
Sets ERROR status (with the error message) on the active span, records the exception event (like tracing::set_error) and sets the Datadog error attributes.
set_error_attributes
Sets the Datadog error attributes (error.type, error.message, error.stack) for err on the active span. No-op without a recording span.
terminated_context
The W3C context that lost against Datadog headers during extract, if any.
terminated_context_links
Span links for a span started from an extracted context: one link to the terminated W3C context (reason=terminated_context, context_headers=tracecontext), or none. Pass them to SpanOptions::link when you export spans without init_tracing’s exporter.
to_datadog_span_id
Converts an OpenTelemetry span id (up to 16 hex characters) to Datadog’s unsigned decimal.
to_datadog_trace_id
Splits an OpenTelemetry trace id (up to 32 hex characters, left-padded) into Datadog’s form. Invalid or all-zero ids are VALIDATION errors.
trace_id_for_path
The id to put in a GET /api/v2/trace/{id} path. Datadog reads an all-digit id as decimal, so a hex id without a letter is sent as its full decimal value; otherwise lower-case hex.
trace_search_query_string
The Datadog query string for a SPEC TraceSearchQuery: service:, resource_name:, @<tag>: and @duration:>= / <= (nanoseconds). An empty query is *.
validate_site
Validates a site name and returns it normalized. A value with a scheme, port, path or other non-host characters (for example https://app.datadoghq.com) is a CONFIG error.
with_datadog_error_attributes
Adds the Datadog error attributes to span when it has none yet: from its last exception event (exception.type, exception.message, exception.stacktrace) or, for an ERROR status without an event, error.message from the status description.
with_terminated_context_link
Adds the terminated-context link (see terminated_context_links) to a span whose remote parent is a Datadog context that won against a conflicting W3C context.

Type Aliases§

DatadogApmError
Service-prefixed alias of Error.
RawDatadogSpan
A raw Datadog span object (any Datadog span shape) decoded from JSON.