AWS X-Ray Exporter for OpenTelemetry .NET

NOTE: This exporter is not affiliated with or officially supported by Amazon.

This is a port of AWS X-Ray Tracing Exporter for OpenTelemetry Collector.

The XRay Exporter exports telemetry to AWS X-Ray service without the need for X-Ray daemon or AWS Distro for Open Telemetry.

Installation

dotnet add package Marius.OpenTelemetry.Exporter.XRay

Traces

using var tracerProvider = Sdk.CreateTracerProviderBuilder() .SetSampler(new AlwaysOnSampler()) .AddSource("DemoSource") .AddXRayExporter() .Build(); }

XRay exporter requires X-Ray compatible trace ids thus overwrites Activity.TraceIdGenerator with a compatible generator. If OpenTelemetry.Contrib.Extensions.AWSXRay is used to generate trace ids then set XRayExporterOptions.GenerateTraceIds = false.

XRayExporterOptions

XRayExporterOptions contains various options to configure the XRay Exporter.

AmazonXRayClientFactory (optional, default: null)

If client factory is not provided then default will be used:

1. If trace provider builder supports dependency injection then the exporter will try to resolve IAmazonXRay from service provider
2. Otherwise a new instance of AmazonXRayClient is created

GenerateTraceIds (optional, default: true)

If true then default trace ids generator will be used. The value false should be only used if OpenTelemetry.Contrib.Extensions.AWSXRay is configured to generate trace ids.

IndexAllAttribute (optional, default: true), IndexedAttributes (optional, default: empty)

If IndexAllAttributes is set to true the all non-XRay tags and attributes are passed as annotations for AWS X-Ray service to be indexed.

If IndexAllAttributes is set to false then only the attributes/tags listed in IndexAttributes will be passed as annotations, other values will be passed as metadata.

IndexedAttributes

A list of attributes to be passed as annotations to X-Ray. Resource attributes must have "otel.resource." prefix.

ShouldIndexAttribute (optional, default: null)

If provided then this function is used to determine which attributes/tags are to be passed via annotations for X-Ray service to be indexed.

ShouldIndexAttribute is only called for attributes that are not in IndexedAttributes list.

If function returns true then attribute/tag is passed as annotation.

If function returns false then attribute/tag is passed as metadata.

Example:

options.IndexAllAttributes = false; // Set to false otherwise ShouldIndexAttribute is ignored options.ShouldIndexAttribute = ShouldIndexAttribute; bool ShouldIndexAttribute(string name, bool isResource) { if (isResource) { // In case of resource the final key is "otel.resource." + name // var key = "otel.resource." + name; if (name == "build" || name.Contains("internal")) { // index otel.resource.key (will ne normalized to otel_resource_key) and // any other key that contains "internal" return true; } return false; } // Only index tenant_id and correlation_id return name == "tenant_id" || name == "correlation_id"; }

Both indexed attributes and function:

options.IndexAllAttributes = false; // Set to false otherwise ShouldIndexAttribute is ignored options.ShouldIndexAttribute = ShouldIndexAttribute; options.IndexedAttributes = new[] { "otel.resource.build", "tenant_id", "correlation_id", }; bool ShouldIndexAttribute(string name, bool isResource) { if (isResource) { // In case of resource the final key is "otel.resource." + name // var key = "otel.resource." + name; return name.Contains("internal"); } // "tenant_id" and "correlation_id" are already indexed // don't index anything else return false; }

IndexActivityNames (optional, default: true)

If true then activity_display_name and activity_operation_name corresponding to Activity.DisplayName and Activity.OperationName are passed as annotations.

ValidateTraceId (optional, default: false)

If true then will reject/ignore activities that have either invalid aws trace id or trace id has expired.

LogGroupNames (optional, default: null)

List of log group names for cloud watch if not provided by resource attributes ("aws.log.group.names" and "aws.log.group.arns").

AllowDotInAnnotationKey (optional, default: false)

If true then dots in attribute keys are allowed and will not be replaced with underscores. Corresponds to BETA feature flag "exporter.xray.allowDot". Original doc: X-Ray Exporter will no longer convert . to _ in annotation keys when this feature gate is enabled.