diff --git a/README.md b/README.md index 074b8926..42ed102f 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,7 @@ documents: * [Installation](./docs/installation.md) * [Configuration](./docs/configuration.md) * [Supported instrumentations](./docs/supported-instrumentations.md) +* [Supported resource detectors](./docs/supported-resource-detectors.md) * [Migrating to upstream](./docs/migration.md) ## Troubleshooting diff --git a/docs/configuration.md b/docs/configuration.md index f7debcef..a44d2e61 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -168,13 +168,44 @@ using var tracerProvider = Sdk.CreateMeterProviderBuilder() Alternatively, instrumentation libraries can be disabled by the environment variable `GRAFANA_DOTNET_DISABLE_INSTRUMENTATIONS`. This variable can be -populated with a comma-separated list of instrumentation library identifiers -from the table above: +populated with a comma-separated list of +[instrumentation library identifiers](./supported-instrumentations.md): ```sh export GRAFANA_DOTNET_DISABLE_INSTRUMENTATIONS="Process,NetRuntime" ``` +### Adding instrumentations not supported by the distribution + +Instrumentations not included in the distribution can easily be added by +extension methods on the tracer and meter provider. + +For example, if it is desired to use the `EventCounters` instrumentation, which is +not included in the [full package](./installation.md#install-the-full-package-with-all-available-instrumentations), +one install the `EventCounters` instrumentation library along with the base +package. + +```sh +dotnet add package --prerelease Grafana.OpenTelemetry.Base +dotnet add package OpenTelemetry.Instrumentation.EventCounters --prerelease +``` + +Then, the `EventCounters` instrumentation can be enabled via the [`AddEventCountersInstrumentation`](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.EventCounters#step-2-enable-eventcounters-instrumentation) +extension method, alongside the `UseGrafana` method. + +```csharp +using var tracerProvider = Sdk.CreateTracerProviderBuilder() + .UseGrafana() + .AddEventCountersInstrumentation(options => { + options.RefreshIntervalSecs = 1; + options.AddEventSources("MyEventSource"); + }) + .Build(); +``` + +This way, any other instrumentation library [not supported by the distribution](./supported-instrumentations.md) +can be added according to the documentation provided with it. + ## Resource detector configuration ### Specifying resource detectors @@ -193,11 +224,12 @@ using var tracerProvider = Sdk.CreateMeterProviderBuilder() ``` Alternatively, resource detectors can be specified by the environment -variable `GRAFANA_DOTNET_RESOURCEDETECTORS`. This variable can be -populated with a comma-separated list of resource detector identifiers: +variable `GRAFANA_DOTNET_RESOURCE_DETECTORS`. This variable can be +populated with a comma-separated list of +[resource detector identifiers](./supported-resource-detectors.md): ```sh -export GRAFANA_DOTNET_RESOURCEDETECTORS="Process" +export GRAFANA_DOTNET_RESOURCE_DETECTORS="Process" ``` ### Disabling resource detectors @@ -217,42 +249,31 @@ using var tracerProvider = Sdk.CreateMeterProviderBuilder() ``` Alternatively, resource detectors can be disabled by the environment -variable `GRAFANA_DOTNET_DISABLE_RESOURCEDETECTORS`. This variable can be +variable `GRAFANA_DOTNET_DISABLE_RESOURCE_DETECTORS`. This variable can be populated with a comma-separated list of resource detector identifiers: ```sh -export GRAFANA_DOTNET_DISABLE_RESOURCEDETECTORS="Host,Process" +export GRAFANA_DOTNET_DISABLE_RESOURCE_DETECTORS="Host,Process" ``` -### Adding instrumentations not supported by the distribution +### Adding resource detectors not supported by the distribution -Instrumentations not included in the distribution can easily be added by +Resource detectors not included in the distribution can easily be added by extension methods on the tracer and meter provider. -For example, if it is desired to use the `EventCounters` instrumentation, which is -not included in the [full package](./installation.md#install-the-full-package-with-all-available-instrumentations), -one install the `EventCounters` instrumentation library along with the base -package. - -```sh -dotnet add package --prerelease Grafana.OpenTelemetry.Base -dotnet add package OpenTelemetry.Instrumentation.EventCounters --prerelease -``` - -Then, the `EventCounters` instrumentation can be enabled via the [`AddEventCountersInstrumentation`](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/tree/main/src/OpenTelemetry.Instrumentation.EventCounters#step-2-enable-eventcounters-instrumentation) +To enable an unsupported resource detector, call the `ConfigureResource` extension method, alongside the `UseGrafana` method. ```csharp using var tracerProvider = Sdk.CreateTracerProviderBuilder() .UseGrafana() - .AddEventCountersInstrumentation(options => { - options.RefreshIntervalSecs = 1; - options.AddEventSources("MyEventSource"); + .ConfigureResource(config => { + config.AddCustomResourceDetector(); }) .Build(); ``` -This way, any other instrumentation library [not supported by the distribution](./supported-instrumentations.md) +This way, any other resource detector library [not supported by the distribution](./supported-resource-detectors.md) can be added according to the documentation provided with it. ### Extra steps to activate specific instrumentations @@ -361,4 +382,4 @@ are not contained in the distribution. | Variable | Example value | Description | | ----------------------------------------- | ------------------ | ----------- | | `GRAFANA_DOTNET_DISABLE_INSTRUMENTATIONS` | "Process,NetRuntime" | A comma-separated list of instrumentations to disable. | -| `GRAFANA_DOTNET_DISABLE_RESOURCEDETECTORS`| "Host" | A comma-separated list of resource detectors to disable. | +| `GRAFANA_DOTNET_DISABLE_RESOURCE_DETECTORS`| "Host" | A comma-separated list of resource detectors to disable. | diff --git a/docs/installation.md b/docs/installation.md index 74bc244a..5a324712 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -39,8 +39,9 @@ package to your project. dotnet add package --prerelease Grafana.OpenTelemetry.Base ``` -The list of [supported instrumentations](./supported-instrumentations.md) -specifies what instrumentations are included in the base package. +The list of [supported instrumentations](./supported-instrumentations.md) and +[supported resource detectors](./supported-resource-detectors.md) +specify which are included in the base package and enabled by default. ## Minimizing unneeded dependencies @@ -52,8 +53,8 @@ dependencies. To mitigate this situation, [base package](#install-the-base-package) with a built-in lazy-loading mechanism can be used. This mechanism will -initialize any known available instrumentation library assembly, regardless of -whether it's added as dependency of the [full package](#install-the-full-package-with-all-available-instrumentations) +initialize known available instrumentation library or resource detectors +assembly, regardless of whether it's added as dependency of the [full package](#install-the-full-package-with-all-available-instrumentations) or as part of the instrumented project. For example, if it is desired to use the `AspNetCore` instrumentation without @@ -76,5 +77,6 @@ using var tracerProvider = Sdk.CreateTracerProviderBuilder() .Build(); ``` -This way, any other instrumentation library [supported by the distribution](./supported-instrumentations.md) -can be added via lazy loading. +This way, any other [instrumentation library](./supported-instrumentations.md) +or [resource detector](./supported-resource-detectors.md) supported by the +distribution can be added via lazy loading. diff --git a/docs/supported-resource-detectors.md b/docs/supported-resource-detectors.md new file mode 100644 index 00000000..7afdae1b --- /dev/null +++ b/docs/supported-resource-detectors.md @@ -0,0 +1,22 @@ +# Supported resource detectors + +The following resource detectors are recognized: + +| Identifier | Enabled by default | Pre-installed | Library name | +| --------------------- | ------------------ | ------------------ | ------------ | +| `AWSEBS` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) | +| `AWSEC2` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) | +| `AWSECS` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) | +| `AWSEKS` | | | [OpenTelemetry.Resources.AWS](https://www.nuget.org/packages/OpenTelemetry.Resources.AWS) | +| `AzureAppService` | | | [OpenTelemetry.Resources.Azure](https://www.nuget.org/packages/OpenTelemetry.Resources.Azure) | +| `AzureVM` | | | [OpenTelemetry.Resources.Azure](https://www.nuget.org/packages/OpenTelemetry.Resources.Azure) | +| `AzureContainerApps` | | | [OpenTelemetry.Resources.Azure](https://www.nuget.org/packages/OpenTelemetry.Resources.Azure) | +| `Container` | | :heavy_check_mark: | [OpenTelemetry.Resources.Container](https://www.nuget.org/packages/OpenTelemetry.Resources.Container) | +| `Host` | :heavy_check_mark: | :heavy_check_mark: | [OpenTelemetry.Resources.Host](https://www.nuget.org/packages/OpenTelemetry.Resources.Host) | +| `OperatingSystem` | | | [OpenTelemetry.Resources.OperatingSystem](https://www.nuget.org/packages/OpenTelemetry.Resources.OperatingSystem) | +| `Process` | :heavy_check_mark: | :heavy_check_mark: | [OpenTelemetry.Resources.Process](https://www.nuget.org/packages/OpenTelemetry.Resources.Process) | +| `ProcessRuntime` | :heavy_check_mark: | :heavy_check_mark: | [OpenTelemetry.Resources.ProcessRuntime](https://www.nuget.org/packages/OpenTelemetry.Resources.ProcessRuntime) | + +* The `Container` resource detector is included but needs to be explicitly + activated, as activating it in non-container environments can causes erroneous + attributes. A future release may activate it by default. diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEBSDetectorInitializer.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEBSDetectorInitializer.cs index ee368208..c8e9b122 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEBSDetectorInitializer.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEBSDetectorInitializer.cs @@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry { internal class AWSEBSDetectorInitializer : ResourceDetectorInitializer { - public override ResourceDetector Id { get; } = ResourceDetector.AWSEBSDetector; + public override ResourceDetector Id { get; } = ResourceDetector.AWSEBS; protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder) { diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEC2DetectorInitializer.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEC2DetectorInitializer.cs index a1ef0d26..cfd1dd05 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEC2DetectorInitializer.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEC2DetectorInitializer.cs @@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry { internal class AWSEC2DetectorInitializer : ResourceDetectorInitializer { - public override ResourceDetector Id { get; } = ResourceDetector.AWSEC2Detector; + public override ResourceDetector Id { get; } = ResourceDetector.AWSEC2; protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder) { diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSECSDetectorInitializer.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSECSDetectorInitializer.cs index 7416c875..37ed56d6 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSECSDetectorInitializer.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSECSDetectorInitializer.cs @@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry { internal class AWSECSDetectorInitializer : ResourceDetectorInitializer { - public override ResourceDetector Id { get; } = ResourceDetector.AWSECSDetector; + public override ResourceDetector Id { get; } = ResourceDetector.AWSECS; protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder) { diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEKSDetectorInitializer.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEKSDetectorInitializer.cs index 1654894c..030192cc 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEKSDetectorInitializer.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AWSEKSDetectorInitializer.cs @@ -10,7 +10,7 @@ namespace Grafana.OpenTelemetry { internal class AWSEKSDetectorInitializer : ResourceDetectorInitializer { - public override ResourceDetector Id { get; } = ResourceDetector.AWSEKSDetector; + public override ResourceDetector Id { get; } = ResourceDetector.AWSEKS; protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder) { diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureAppServiceDetectorInitializer.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureAppServiceDetectorInitializer.cs index aaff5f45..eaaffe1e 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureAppServiceDetectorInitializer.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureAppServiceDetectorInitializer.cs @@ -9,7 +9,7 @@ namespace Grafana.OpenTelemetry { internal class AzureAppServiceDetectorInitializer : ResourceDetectorInitializer { - public override ResourceDetector Id { get; } = ResourceDetector.AzureAppServiceDetector; + public override ResourceDetector Id { get; } = ResourceDetector.AzureAppService; protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder) { diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureContainerAppsDetectorInitializer.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureContainerAppsDetectorInitializer.cs index e401007d..e2beecc3 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureContainerAppsDetectorInitializer.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureContainerAppsDetectorInitializer.cs @@ -9,7 +9,7 @@ namespace Grafana.OpenTelemetry { internal class AzureContainerAppsDetectorInitializer : ResourceDetectorInitializer { - public override ResourceDetector Id { get; } = ResourceDetector.AzureContainerAppsDetector; + public override ResourceDetector Id { get; } = ResourceDetector.AzureContainerApps; protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder) { diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureVMDetectorInitializer.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureVMDetectorInitializer.cs index 4b03c753..dcff5ffd 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureVMDetectorInitializer.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/AzureVMDetectorInitializer.cs @@ -9,7 +9,7 @@ namespace Grafana.OpenTelemetry { internal class AzureVMDetectorInitializer : ResourceDetectorInitializer { - public override ResourceDetector Id { get; } = ResourceDetector.AzureVMDetector; + public override ResourceDetector Id { get; } = ResourceDetector.AzureVM; protected override ResourceBuilder InitializeResourceDetector(ResourceBuilder builder) { diff --git a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/ResourceDetector.cs b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/ResourceDetector.cs index 2f5c201f..9de6ac71 100644 --- a/src/Grafana.OpenTelemetry.Base/ResourceDetectors/ResourceDetector.cs +++ b/src/Grafana.OpenTelemetry.Base/ResourceDetectors/ResourceDetector.cs @@ -11,57 +11,57 @@ namespace Grafana.OpenTelemetry public enum ResourceDetector { /// - /// AWS EBS Resource Detector (OpenTelemetry.ResourceDetectors.AWS) + /// AWS EBS Resource Detector (OpenTelemetry.Resources.AWS) /// - AWSEBSDetector, + AWSEBS, /// - /// AWS EC2 Resource Detector (OpenTelemetry.ResourceDetectors.AWS) + /// AWS EC2 Resource Detector (OpenTelemetry.Resources.AWS) /// - AWSEC2Detector, + AWSEC2, /// - /// AWS ECS Resource Detector (OpenTelemetry.ResourceDetectors.AWS) + /// AWS ECS Resource Detector (OpenTelemetry.Resources.AWS) /// - AWSECSDetector, + AWSECS, /// - /// AWS EKS Resource Detector (OpenTelemetry.ResourceDetectors.AWS) + /// AWS EKS Resource Detector (OpenTelemetry.Resources.AWS) /// - AWSEKSDetector, + AWSEKS, /// - /// Azure App Service Resource Detector (OpenTelemetry.ResourceDetectors.Azure) + /// Azure App Service Resource Detector (OpenTelemetry.Resources.Azure) /// - AzureAppServiceDetector, + AzureAppService, /// - /// Azure Virtual Machine Resource Detector (OpenTelemetry.ResourceDetectors.Azure) + /// Azure Virtual Machine Resource Detector (OpenTelemetry.Resources.Azure) /// - AzureVMDetector, + AzureVM, /// - /// Azure Container Apps Resource Detector (OpenTelemetry.ResourceDetectors.Azure) + /// Azure Container Apps Resource Detector (OpenTelemetry.Resources.Azure) /// - AzureContainerAppsDetector, + AzureContainerApps, /// - /// Container Resource Detector (OpenTelemetry.ResourceDetectors.Container) + /// Container Resource Detector (OpenTelemetry.Resources.Container) /// Container, /// - /// Host Resource Detector (OpenTelemetry.ResourceDetectors.Host) + /// Host Resource Detector (OpenTelemetry.Resources.Host) /// Host, /// - /// Operating System Resource Detector (OpenTelemetry.ResourceDetectors.OperatingSystem) + /// Operating System Resource Detector (OpenTelemetry.Resources.OperatingSystem) /// OperatingSystem, /// - /// Process Resource Detector (OpenTelemetry.ResourceDetectors.Process) + /// Process Resource Detector (OpenTelemetry.Resources.Process) /// Process, /// - /// Process Runtime Resource Detector (OpenTelemetry.ResourceDetectors.ProcessRuntime) + /// Process Runtime Resource Detector (OpenTelemetry.Resources.ProcessRuntime) /// ProcessRuntime } diff --git a/tests/Grafana.OpenTelemetry.Tests/ResourceDetectorTest.cs b/tests/Grafana.OpenTelemetry.Tests/ResourceDetectorTest.cs index 1b577dbf..b66b0ef9 100644 --- a/tests/Grafana.OpenTelemetry.Tests/ResourceDetectorTest.cs +++ b/tests/Grafana.OpenTelemetry.Tests/ResourceDetectorTest.cs @@ -17,12 +17,12 @@ public void EnumMatchesInitializers() { var expected = new HashSet((ResourceDetector[])Enum.GetValues(typeof(ResourceDetector))); #if NETSTANDARD - expected.Remove(ResourceDetector.AWSEBSDetector); - expected.Remove(ResourceDetector.AWSEC2Detector); + expected.Remove(ResourceDetector.AWSEBS); + expected.Remove(ResourceDetector.AWSEC2); #endif #if NETSTANDARD || NETFRAMEWORK - expected.Remove(ResourceDetector.AWSECSDetector); - expected.Remove(ResourceDetector.AWSEKSDetector); + expected.Remove(ResourceDetector.AWSECS); + expected.Remove(ResourceDetector.AWSEKS); #endif #if !NET6_0_OR_GREATER expected.Remove(ResourceDetector.Container);