OpenTelemetry .NET distro for Uptrace

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

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

Uptrace .NET

uptrace-dotnet is a lightweight wrapper around opentelemetry-dotnet that pre-configures the OpenTelemetry SDK to export data to Uptrace. It doesn't add new functionality but simplifies the setup process for your convenience.

Installation

To install uptrace-dotnet:

shell

dotnet add package Uptrace.OpenTelemetry --prerelease

Note: You can skip this step if you're already using the OTLP exporter.

Configuration

Configure the Uptrace client using a DSN (Data Source Name) from your project settings page. Replace <FIXME> with your actual Uptrace DSN and myservice with a name that identifies your application.

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("<FIXME>")
    .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

Follow this 5-minute guide to install the OpenTelemetry distro, generate your first trace, and view it in the Uptrace dashboard.

Step 0: Create Uptrace Project

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

Step 1: Clone the Example

Clone the basic example:

shell

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

Step 2: Run the Example

Execute the example, replacing <FIXME> with your Uptrace DSN:

shell

UPTRACE_DSN="<FIXME>" dotnet run

You should see output similar to:

text

https://app.uptrace.dev/traces/<trace_id>

Step 3: View the Trace

Click the generated link to view your trace in the Uptrace dashboard:

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 data before sending and reduce traffic costs.	All	Essential
Prefer `delta` metrics temporality, because such metrics are smaller and Uptrace converts `cumulative` metrics to `delta` anyway.	Metrics	Recommended
Prefer Protobuf over JSON as a generally more efficient encoding. Feel free to continue using JSON encoding with JavaScript.	All	Recommended
Prefer HTTP over gRPC as a more mature transport with better compatibility.	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://api.uptrace.dev:4317	4317
HTTPS	https://api.uptrace.dev	443

Most languages allow to configure OTLP exporter using environment variables:

shell

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

# Pass Uptrace DSN in gRPC/HTTP headers.
export OTEL_EXPORTER_OTLP_HEADERS="uptrace-dsn=<FIXME>"

# 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:

shell

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

# Maximum batch size.
# Using larger batch sizes can cause issues,
# because Uptrace rejects requests larger than 32MB.
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 issues with OpenTelemetry .NET, try these troubleshooting guides:

Common Issues

No data appearing in Uptrace:

Verify your DSN is correctly configured
Check that your application is generating spans/metrics
Ensure network connectivity to Uptrace endpoints

Performance issues:

Adjust sampling rates if collecting too much data
Review instrumentation configuration for unnecessary overhead

What's next?

Troubleshooting

Tracing API