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 <[email protected]> * 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 <[email protected]> * Attempt to fix most markdown issues * Slight modifications to hopefully pass the linter Co-authored-by: Fabrizio Ferri-Benedetti <[email protected]> Co-authored-by: Paulo Janotti <[email protected]>
open-telemetry · Apr 20, 2022 · 8ec1d72 · 8ec1d72
1 parent 0e9ea15
commit 8ec1d72
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 57 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -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`,

diff --git a/docs/config.md b/docs/config.md
@@ -2,37 +2,33 @@
 
 ## 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
 
 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.
+The OpenTelemetry .NET Automatic Instrumentation also supports the following
+environment variables for the OTLP exporter:
+| Environment variable | Description | Default value |
+|-|-|-|
+| `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 |
+| 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_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,

diff --git a/docs/internal/config.md b/docs/internal/config.md
@@ -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` |