open-telemetry
/
opentelemetry-dotnet-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Configuration Cleanup for beta release (#495) 

* First pass at documentation cleanup. This may be too aggressive, but I'm happy to discuss. Key changes include:
- Remove public documentation of settings primarily geared toward repo authors
- Split up exporter configurations into smaller sections and redirect to the SDK for all environment variables handled by the SDK.
- Split up the .NET CLR Profiler table into two tables so it's very clear for users to copy/paste environment variable names

* Apply suggestions from code review

Commit Fabrizio's suggestions

Co-authored-by: Fabrizio Ferri-Benedetti <fferribenedetti@splunk.com>

* Add a new file docs/internal/config.md to document configuration settings that are not public-facing

* Combine the .NET Framework and .NET Core environment variable tables again but with improved environmnent variable keys

* Update table columns from "Default" to "Default value" based on feedback

* Add important environment variables to each exporter and add disclaimer about OTEL_EXPORTER_OTLP_PROTOCOL defaulting to protobuf

* Update docs/internal/config.md

Co-authored-by: Paulo Janotti <pjanotti@splunk.com>

* Attempt to fix most markdown issues

* Slight modifications to hopefully pass the linter

Co-authored-by: Fabrizio Ferri-Benedetti <fferribenedetti@splunk.com>
Co-authored-by: Paulo Janotti <pjanotti@splunk.com>
This commit is contained in:
Zach Montoya 2022-04-20 15:41:04 -07:00 committed by GitHub
parent 0e9ea15aaa
commit 8ec1d72cc1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 91 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
CHANGELOG.md
View File

@ -42,19 +42,7 @@ built on top of [OpenTelemetry .NET](https://github.com/open-telemetry/opentelem
`OTEL_DOTNET_AUTO_CLR_ENABLE_NGEN`.
- Support for OpenTelemetry exporter related environment variables:
`OTEL_TRACES_EXPORTER`,
`OTEL_EXPORTER_JAEGER_AGENT_HOST`, `OTEL_EXPORTER_JAEGER_AGENT_PORT`,
`OTEL_EXPORTER_JAEGER_ENDPOINT`,
`OTEL_EXPORTER_JAEGER_PROTOCOL`,
`OTEL_EXPORTER_OTLP_ENDPOINT`,
`OTEL_EXPORTER_OTLP_HEADERS`,
`OTEL_EXPORTER_OTLP_TIMEOUT`,
`OTEL_EXPORTER_OTLP_PROTOCOL`,
`OTEL_EXPORTER_ZIPKIN_ENDPOINT`.
- Support for OpenTelemetry batch span processor related environment variables:
`OTEL_BSP_SCHEDULE_DELAY`,
`OTEL_BSP_EXPORT_TIMEOUT`,
`OTEL_BSP_MAX_QUEUE_SIZE`,
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`.
- Customization and plugin capabilities which can be configured
using the following environment variables:
`OTEL_DOTNET_AUTO_LOAD_AT_STARTUP`,

105
docs/config.md
View File

@ -2,13 +2,12 @@
## Global settings
| Environment variable | Description | Default |
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_DOTNET_AUTO_HOME` | Installation location. | `true` |
| `OTEL_DOTNET_AUTO_HOME` | Installation location. | |
| `OTEL_DOTNET_AUTO_ENABLED` | Enables the tracer. | `true` |
| `OTEL_DOTNET_AUTO_INCLUDE_PROCESSES` | Names of the executable files that the profiler can instrument. Supports multiple comma-separated values, for example: `MyApp.exe,dotnet.exe`. If unset, the profiler attaches to all processes by default. | |
| `OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES` | Names of the executable files that the profiler cannot instrument. Supports multiple comma-separated values, for example: `ReservedProcess.exe,powershell.exe`. The list is processed after `OTEL_DOTNET_AUTO_INCLUDE_PROCESSES`. If unset, the profiler attaches to all processes by default. | |
| `OTEL_DOTNET_AUTO_AZURE_APP_SERVICES` | Set to indicate that the profiler is running in the context of Azure App Services. | `false` |
## Resources
@ -16,23 +15,20 @@ A resource is the immutable representation of the entity producing the telemetry
See [Resource semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/resource/semantic_conventions)
for more details.
| Environment variable | Description | Default |
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_RESOURCE_ATTRIBUTES` | Key-value pairs to be used as resource attributes. See [Resource SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. | See [Resource semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for details. |
| `OTEL_SERVICE_NAME` | Sets the value of the [`service.name`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service) resource attribute. If `service.name` is provided in `OTEL_RESOURCE_ATTRIBUTES`, the value of `OTEL_SERVICE_NAME` takes precedence. | `unknown_service:%ProcessName%` |
## Instrumentations
| Environment variable | Description | Default |
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_DOTNET_AUTO_INTEGRATIONS_FILE` | File path of JSON configuration files of bytecode instrumentations. For example: `%ProfilerDirectory%/integrations.json` | |
| `OTEL_DOTNET_AUTO_ENABLED_INSTRUMENTATIONS` | Comma-separated list of source instrumentations you want to enable. | |
| `OTEL_DOTNET_AUTO_DISABLED_INSTRUMENTATIONS` | Comma-separated list of source and bytecode instrumentations you want to disable. | |
| `OTEL_DOTNET_AUTO_{0}_ENABLED` | Configuration pattern for enabling or disabling specific bytecode. For example, to disable GraphQL instrumentation, set the `OTEL_TRACE_GraphQL_ENABLED` environment variable to `false`. | `true` |
| `OTEL_DOTNET_AUTO_DOMAIN_NEUTRAL_INSTRUMENTATION` | Whether to intercept method calls when the caller method is inside a domain-neutral assembly. Useful when instrumenting IIS applications. | `false` |
| `OTEL_DOTNET_AUTO_CLR_DISABLE_OPTIMIZATIONS` | Set to `true` to disable all JIT optimizations. | `false` |
| `OTEL_DOTNET_AUTO_CLR_ENABLE_INLINING` | Set to `false` to disable JIT inlining. | `true` |
| `OTEL_DOTNET_AUTO_CLR_ENABLE_NGEN` | Set to `false` to disable NGEN images. | `true` |
### Instrumented libraries and frameworks
@ -62,59 +58,82 @@ If the default log directories can't be created,
the instrumentation uses the path of the current user's [temporary folder](https://docs.microsoft.com/en-us/dotnet/api/System.IO.Path.GetTempPath?view=net-6.0)
instead.
| Environment variable | Description | Default |
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_DOTNET_AUTO_LOG_DIRECTORY` | Directory of the .NET Tracer logs. | _See the previous note on default paths_ |
| `OTEL_DOTNET_AUTO_DEBUG` | Enables debugging mode for the tracer. | `false` |
| `OTEL_DOTNET_AUTO_CONSOLE_EXPORTER_ENABLED` | Whether the console exporter is enabled or not. | `false` |
| `OTEL_DOTNET_AUTO_DUMP_ILREWRITE_ENABLED` | Lets the profiler dump the IL original code and modification to the log. | `false` |
## Exporters
Exporters output the telemetry.
| Environment variable | Description | Default |
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_TRACES_EXPORTER` | Traces exporter to be used. The value can be one of the following: `zipkin`, `jaeger`, `otlp`, `none`. | `otlp` |
### Jaeger
To enable the Jaeger exporter, set the `OTEL_TRACES_EXPORTER` environment variable
to `jaeger`. To customize the Jaeger exporter using environment variables, see the
[Jaeger exporter documentation](https://github.com/open-telemetry/opentelemetry-dotnet/tree/core-1.2.0/src/OpenTelemetry.Exporter.Jaeger#environment-variables).
Important environment variables include:
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_EXPORTER_JAEGER_AGENT_HOST` | Host name for the Jaeger agent. Used for the `udp/thrift.compact` protocol.| `localhost` |
| `OTEL_EXPORTER_JAEGER_AGENT_PORT` | Port for the Jaeger agent. Used for the `udp/thrift.compact` protocol. | `6831` |
| `OTEL_EXPORTER_JAEGER_ENDPOINT` | Jaeger Collector HTTP endpoint. Used for the `http/thrift.binary` protocol. | `http://localhost:14268` |
| `OTEL_EXPORTER_JAEGER_PROTOCOL` | Protocol to use for Jager exporter. Supported values are `udp/thrift.compact`, `http/thrift.binary` | `udp/thrift.compact` |
### OTLP
To enable the OTLP exporter, set the `OTEL_TRACES_EXPORTER` environment variable
to `otlp`. To customize the OTLP exporter using environment variables, see the
[OTLP exporter documentation](https://github.com/open-telemetry/opentelemetry-dotnet/tree/core-1.2.0/src/OpenTelemetry.Exporter.OpenTelemetryProtocol#environment-variables).
Important environment variables include:
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Target endpoint for the OTLP exporter. See [the OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md) for more details. | `http://localhost:4318` for the `http/protobuf` protocol, `http://localhost:4317` for the `grpc` protocol |
| `OTEL_EXPORTER_OTLP_HEADERS` | Key-value pairs to be used as headers associated with gRPC or HTTP requests. See the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md) for more details. | |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | Maximum amount of time the OTLP exporter waits for each batch export. | `1000` (ms) |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP exporter transport protocol. Supported values are `grpc`, `http/protobuf`. [1] | `http/protobuf` |
| `OTEL_EXPORTER_ZIPKIN_ENDPOINT` | Zipkin URL. | `http://localhost:8126` |
| `OTEL_DOTNET_AUTO_HTTP2UNENCRYPTEDSUPPORT_ENABLED` | Enables `System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport`. Required when instrumenting .NET Core 3.x applications while using a non-TLS endpoint for gRPC OTLP. See the [official Microsoft documentation](https://docs.microsoft.com/en-us/aspnet/core/grpc/troubleshoot?view=aspnetcore-6.0#call-insecure-grpc-services-with-net-core-client) for more details. | `false` |
**[1]**: Considerations on the `OTEL_EXPORTER_OTLP_PROTOCOL`:
- The OpenTelemetry .NET Automatic Instrumentation defaults to `http/protobuf`,
which differs from the OpenTelemetry .NET SDK default value of `grpc`.
- On .NET 5 and higher, the application must reference [`Grpc.Net.Client`](https://www.nuget.org/packages/Grpc.Net.Client/)
to use the `grpc` OTLP exporter protocol. For example, by adding
`<PackageReference Include="Grpc.Net.Client" Version="2.32.0" />` to the `.csproj`
file.
`<PackageReference Include="Grpc.Net.Client" Version="2.32.0" />` to the
`.csproj` file.
- On .NET Framework, the `grpc` OTLP exporter protocol is not supported.
## Batch span processor
The batch span processor batches finished spans before sending them through the exporter.
| Environment variable | Description | Default |
The OpenTelemetry .NET Automatic Instrumentation also supports the following
environment variables for the OTLP exporter:
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_BSP_SCHEDULE_DELAY` | Delay interval between two consecutive exports. | `5000` (ms) |
| `OTEL_BSP_EXPORT_TIMEOUT` | Maximum allowed time to export data. | `30000` (ms) |
| `OTEL_BSP_MAX_QUEUE_SIZE` | Maximum queue size. | `2048` |
| `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | Maximum batch size. Must be less than or equal to `OTEL_BSP_MAX_QUEUE_SIZE`. | `512` (ms) |
| `OTEL_DOTNET_AUTO_HTTP2UNENCRYPTEDSUPPORT_ENABLED` | Enables `System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport`. Required when instrumenting .NET Core 3.x applications while using a non-TLS endpoint for gRPC OTLP. See the [official Microsoft documentation](https://docs.microsoft.com/en-us/aspnet/core/grpc/troubleshoot?view=aspnetcore-6.0#call-insecure-grpc-services-with-net-core-client) for more details. | `false` |
### Zipkin
To enable the Zipkin exporter, set the `OTEL_TRACES_EXPORTER` environment
variable to `zipkin`. To customize the Zipkin exporter using environment
variables, see the [Zipkin exporter documentation](https://github.com/open-telemetry/opentelemetry-dotnet/tree/core-1.2.0/src/OpenTelemetry.Exporter.Zipkin#configuration-using-environment-variables).
Important environment variables include:
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_EXPORTER_ZIPKIN_ENDPOINT` | Zipkin URL. | `http://localhost:8126` |
## Additional settings
| Environment variable | Description | Default |
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_DOTNET_AUTO_LOAD_AT_STARTUP` | Whether the tracer is created by the automatic instrumentation library or not. Set to `false` when the application initializes the OpenTelemetry .NET SDK Tracer on its own. This configuration can be used, for example, to retrieve the bytecode instrumentations. | `true` |
| `OTEL_DOTNET_AUTO_ADDITIONAL_SOURCES` | Comma-separated list of additional `ActivitySource` names to be added to the tracer at the startup. Use it to capture manually instrumented spans. | |
| `OTEL_DOTNET_AUTO_LEGACY_SOURCES` | Comma-separated list of additional legacy source names to be added to the tracer at the startup. Use it to capture `Activity` objects created without using the `ActivitySource` API. | |
| `OTEL_DOTNET_AUTO_ADDITIONAL_SOURCES` | Comma-separated list of additional `System.Diagnostics.ActivitySource` names to be added to the tracer at the startup. Use it to capture manually instrumented spans. | |
| `OTEL_DOTNET_AUTO_LEGACY_SOURCES` | Comma-separated list of additional legacy source names to be added to the tracer at the startup. Use it to capture `System.Diagnostics.Activity` objects created without using the `System.Diagnostics.ActivitySource` API. | |
| `OTEL_DOTNET_AUTO_FLUSH_ON_UNHANDLEDEXCEPTION` | Controls whether the telemetry data is flushed when an [AppDomain.UnhandledException](https://docs.microsoft.com/en-us/dotnet/api/system.appdomain.unhandledexception) event is raised. Set to `true` when you suspect that you are experiencing a problem with missing telemetry data and also experiencing unhandled exceptions. | `false` |
| `OTEL_DOTNET_AUTO_INSTRUMENTATION_PLUGINS` | Colon-separated list of OTel SDK instrumentation plugins represented by `System.Type.AssemblyQualifiedName`. | |
| `OTEL_DOTNET_AUTO_INSTRUMENTATION_PLUGINS` | Colon-separated list of OTel SDK instrumentation plugin types, specified with the [assembly-qualified name](https://docs.microsoft.com/en-us/dotnet/api/system.type.assemblyqualifiedname?view=net-6.0#system-type-assemblyqualifiedname). _Note: This list must be colon-separated because the type names may include commas._ | |
You can use `OTEL_DOTNET_AUTO_INSTRUMENTATION_PLUGINS` to extend the
configuration of the OpenTelemetry .NET SDK Tracer. A plugin must be a
@ -132,24 +151,18 @@ OpenTelemetry .NET Automatic Instrumentation.
To perform bytecode instrumentation, configure the OpenTelemetry .NET
Automatic Instrumentation as a .NET CLR Profiler. The CLR uses the following
environment variables to set up the profiler.
> Notice that .NET Framework uses the `COR_` prefix instead of `CORECLR_`.
| Environment variable | Description | Value |
|-|-|-|
| `CORECLR_ENABLE_PROFILING` | Enables the profiler. | `1` |
| `CORECLR_PROFILER` | CLSID of the profiler. | `30000` (ms) |
| `CORECLR_PROFILER_PATH` | Path to the profiler. | `%InstallationLocation%/OpenTelemetry.AutoInstrumentation.Native.so` for Linux, `%InstallationLocation%/OpenTelemetry.AutoInstrumentation.Native.dylib` for MacOS |
| `CORECLR_PROFILER_PATH_32` | Path to the 32-bit profiler. Bitness-specific paths take precedence over generic paths. | `%InstallationLocation%/win-x86/OpenTelemetry.AutoInstrumentation.Native.dll` for Windows |
| `CORECLR_PROFILER_PATH_64` | Path to the 64-bit profiler. Bitness-specific paths take precedence over generic paths. | `%InstallationLocation%/win-x64/OpenTelemetry.AutoInstrumentation.Native.dll` for Windows |
The `*_PROFILER_PATH_*` environment variable is not needed on Windows if the DLL
file is already registered.
See [.NET Runtime Profiler Loading](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/profiling/Profiler%20Loading.md)
environment variables to set up the profiler. See
[.NET Runtime Profiler Loading](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/profiling/Profiler%20Loading.md)
for more information.
| .NET Framework environment variable | .NET Core environment variable | Description | Required value |
|-|-|-|-|
| `COR_ENABLE_PROFILING` | `CORECLR_ENABLE_PROFILING` | Enables the profiler. | `1` |
| `COR_PROFILER` | `CORECLR_PROFILER` | CLSID of the profiler. | `{918728DD-259F-4A6A-AC2B-B85E1B658318}` |
| `COR_PROFILER_PATH` | `CORECLR_PROFILER_PATH` | Path to the profiler. | `%InstallationLocation%/OpenTelemetry.AutoInstrumentation.Native.dll` for Windows, `%InstallationLocation%/OpenTelemetry.AutoInstrumentation.Native.so` for Linux, `%InstallationLocation%/OpenTelemetry.AutoInstrumentation.Native.dylib` for MacOS |
| `COR_PROFILER_PATH_32` | `CORECLR_PROFILER_PATH_32` | Path to the 32-bit profiler. Bitness-specific paths take precedence over generic paths. | `%InstallationLocation%/win-x86/OpenTelemetry.AutoInstrumentation.Native.dll` for Windows |
| `COR_PROFILER_PATH_64` | `CORECLR_PROFILER_PATH_64` | Path to the 64-bit profiler. Bitness-specific paths take precedence over generic paths. | `%InstallationLocation%/win-x64/OpenTelemetry.AutoInstrumentation.Native.dll` for Windows |
## .NET Runtime additional dependencies and package store
To resolve assembly version conflicts in .NET Core,

32
docs/internal/config.md Normal file
View File

@ -0,0 +1,32 @@
# Configuration
This document lists advanced configuration settings rarely changed by users.
## Environment
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_DOTNET_AUTO_AZURE_APP_SERVICES` | Set to indicate that the profiler is running in the context of Azure App Services. | `false` |
## Diagnostics
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_DOTNET_AUTO_DUMP_ILREWRITE_ENABLED` | Lets the profiler dump the IL original code and modification to the log. | `false` |
## CLR Optimizations
Bytecode instrumentations are implemented by registering a CLR Profiler, receiving
notifications from the .NET runtime, and rewriting methods at runtime to invoke the
appropriate instrumentation. The CLR Profiler components of this library have been
authored to run with as much of the CLR optimizations enabled as possible, but under
rare circumstances it is possible that the optimizations have caused rewriting
not to run, resulting in missing spans. To determine whether CLR optimizations
are affecting instrumentations, you may set the following configurations to
modify CLR optimizations.
| Environment variable | Description | Default value |
|-|-|-|
| `OTEL_DOTNET_AUTO_CLR_DISABLE_OPTIMIZATIONS` | Set to `true` to disable all JIT optimizations. | `false` |
| `OTEL_DOTNET_AUTO_CLR_ENABLE_INLINING` | Set to `false` to disable JIT inlining. | `true` |
| `OTEL_DOTNET_AUTO_CLR_ENABLE_NGEN` | Set to `false` to disable NGEN images. | `true` |