open-telemetry / opentelemetry-dotnet

Troubleshooting - open-telemetry/opentelemetry-dotnet

Troubleshooting Common Issues with OpenTelemetry.NET

OpenTelemetry.NET is a powerful tool for distributed tracing and monitoring. However, you might encounter issues during its implementation. This guide provides solutions to common problems, with examples and references to official documentation.

  1. Telemetry not appearing in the console

If you can’t see telemetry data in the console, ensure that the following environment variables are set to true before launching your application:

  • OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED
  • OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED
  • OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED

For more information, see the OpenTelemetry .NET SDK documentation on supported libraries and frameworks.

  1. Troubleshooting .NET automatic instrumentation issues

If you encounter any issue with OpenTelemetry .NET Automatic Instrumentation, follow these steps:

  • Enable detailed logging: Set the OTEL_LOG_LEVEL environment variable to debug before the instrumented process starts. This will generate detailed logs that can help you troubleshoot instrumentation issues.
  • Check log locations: By default, the library writes log files under predefined locations. You can change the default location by updating the OTEL_DOTNET_AUTO_LOG_DIRECTORY environment variable.

For more information, see the troubleshooting guide for .NET automatic instrumentation.

  1. Confirming the process.runtime.name value

The process.runtime.name value should be set correctly based on the runtime. For .NET Core, .NET 5+, and .NET Framework, it should be set to dotnet-core, dotnet-framework, or mono, respectively.

For more information, see the resource semantic conventions documentation.

  1. Receiver issues

If your telemetry client generates data but it hasn’t been received by your backend, check the otelcol_receiver_accepted_spans metric to ensure that the data point has been received by the Collector. If it hasn’t, check the otelcol_receiver_refused_spans metric to ensure it wasn’t refused by the Collector.

For more information, see the troubleshooting guide for the OpenTelemetry Collector.

  1. Sending test data

For certain types of issues, particularly verifying configuration and debugging network issues, it can be helpful to send a small amount of data to a collector configured to output to local logs.

For more information, see the recommendations for troubleshooting the collector.

  1. Checklist for debugging complex pipelines

When telemetry flows through multiple collectors and networks, it’s important to verify the health of each “hop” of telemetry data through a collector or other component in your telemetry pipeline.

For more information, see the recommendations for troubleshooting the collector.

These are some common issues and solutions for OpenTelemetry.NET. For more information, refer to the official OpenTelemetry .NET documentation.