OpenTelemetry .NET distro for Uptrace

This document explains how to configure OpenTelemetry .NET SDK to export spans and metrics to Uptrace using OTLP/gRPC.

To learn about OpenTelemetry API, see OpenTelemetry .NET Tracing API and OpenTelemetry .NET Metrics API.

• Uptrace .NET
  • Configuration
  • Quickstart
• Already using OTLP exporter?
• Troubleshooting
• What's next?

Uptrace .NET

uptrace-dotnet is a thin wrapper over opentelemetry-dotnet that configures OpenTelemetry SDK to export data to Uptrace. It does not add any new functionality and is provided only for your convenience.

To install uptrace-dotnet:

dotnet add package Uptrace.OpenTelemetry --prerelease

Configuration

You can configure Uptrace client using a DSN (Data Source Name) from the project settings page.

using System;
using System.Diagnostics;

using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;

using Uptrace.OpenTelemetry;

var serviceName = "myservice";
var serviceVersion = "1.0.0";

var openTelemetry = Sdk.CreateTracerProviderBuilder()
    .AddSource("*") // subscribe to all activity sources
    .SetResourceBuilder(
        ResourceBuilder
            .CreateDefault()
            .AddEnvironmentVariableDetector()
            .AddTelemetrySdk()
            .AddService(serviceName: serviceName, serviceVersion: serviceVersion)
    )
    // copy your project DSN here or use UPTRACE_DSN env var
    //.AddUptrace("https://FIXME@api.uptrace.dev?grpc=4317")
    .AddUptrace()
    .Build();

You can also use environment variables to configure the client:

Env var	Description
UPTRACE_DSN	A data source that is used to connect to uptrace.dev. For example, https://<token>@uptrace.dev/<project_id>.
OTEL_RESOURCE_ATTRIBUTES	Key-value pairs to be used as resource attributes. For example, service.name=myservice,service.version=1.0.0.
OTEL_SERVICE_NAME=myservice	Sets the value of the service.name resource attribute. Takes precedence over OTEL_RESOURCE_ATTRIBUTES.
OTEL_PROPAGATORS	Propagators to be used as a comma separated list. The default is tracecontext,baggage.

See OpenTelemetry documentation for details.

Quickstart

Spend 5 minutes to install OpenTelemetry distro, generate your first trace, and click the link in your terminal to view the trace.

• Step 0. Create an Uptrace project to obtain a DSN (connection string), for example, https://<token>@api.uptrace.dev?grpc=4317.

• Step 1. Clone the basic example:

git clone https://github.com/uptrace/uptrace-dotnet/tree/master/example/basic
cd example/basic

• Step 2. Run the example to get a link for the generated trace:

$ UPTRACE_DSN="https://FIXME@api.uptrace.dev?grpc=4317" dotnet run
https://uptrace.dev/traces/<trace_id>

• Step 3. Follow the link to view the trace:

Already using OTLP exporter?

If you are already using OTLP exporter, you can continue to use it with Uptrace by changing some configuration options.

To maximize performance and efficiency, consider the following recommendations when configuring OpenTelemetry SDK.

Recommendation	Signals	Significance
Use BatchSpanProcessor to export multiple spans in a single request.	All	Essential
Enable gzip compression to compress the data before sending and reduce the traffic cost.	All	Essential
Prefer delta metrics temporality, because such metrics are smaller and Uptrace must convert cumulative metrics to delta anyway.	Metrics	Recommended
Prefer Protobuf encoding over JSON.	All	Recommended
Use AWS X-Ray ID generator for OpenTelemetry.	Traces, Logs	Optional

To configure OpenTelemetry to send data to Uptrace, use the provided endpoint and pass the DSN via uptrace-dsn header:

Transport	Endpoint	Port
gRPC	https://otlp.uptrace.dev:4317	4317
HTTPS	https://otlp.uptrace.dev	443

Most languages allow to configure OTLP exporter using environment variables:

# Uncomment the appropriate protocol for your programming language.
# Only for OTLP/gRPC
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.uptrace.dev:4317"
# Only for OTLP/HTTP
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp.uptrace.dev"

# Pass Uptrace DSN in gRPC/HTTP headers.
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=https://FIXME@api.uptrace.dev?grpc=4317"

# Enable gzip compression.
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

# Enable exponential histograms.
export OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=BASE2_EXPONENTIAL_BUCKET_HISTOGRAM

# Prefer delta temporality.
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA

When configuring BatchSpanProcessor, use the following settings:

# Maximum allowed time to export data in milliseconds.
export OTEL_BSP_EXPORT_TIMEOUT=10000

# Maximum batch size.
# Using larger batch sizes can be problematic,
# because Uptrace rejects requests larger than 20MB.
export OTEL_BSP_MAX_EXPORT_BATCH_SIZE=10000

# Maximum queue size.
# Increase queue size if you have lots of RAM, for example,
# `10000 * number_of_gigabytes`.
export OTEL_BSP_MAX_QUEUE_SIZE=30000

# Max concurrent exports.
# Setting this to the number of available CPUs might be a good idea.
export OTEL_BSP_MAX_CONCURRENT_EXPORTS=2

Troubleshooting

If you encounter any issue with OpenTelemetry .NET, try the following guides:

• OpenTelemetry .NET
• OpenTelemetry .NET instrumentation

What's next?

Next, instrument more operations to get a more detailed picture. Try to prioritize network calls, disk operations, database queries, error and logs.

You can also create your own instrumentations using OpenTelemetry .NET Tracing API.