Updates installation and configuration documentation for GA release (g…

…rafana#119)

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

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. |

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.

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.

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)
         {

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)
         {

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)
         {

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)
         {

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)
         {

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)
         {

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)
         {

src/Grafana.OpenTelemetry.Base/ResourceDetectors/ResourceDetector.cs

@@ -11,57 +11,57 @@ namespace Grafana.OpenTelemetry
     public enum ResourceDetector
     {
         /// <summary>
-        /// AWS EBS Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
+        /// AWS EBS Resource Detector (OpenTelemetry.Resources.AWS)
         /// </summary>
-        AWSEBSDetector,
+        AWSEBS,
         /// <summary>
-        /// AWS EC2 Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
+        /// AWS EC2 Resource Detector (OpenTelemetry.Resources.AWS)
         /// </summary>
-        AWSEC2Detector,
+        AWSEC2,
         /// <summary>
-        /// AWS ECS Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
+        /// AWS ECS Resource Detector (OpenTelemetry.Resources.AWS)
         /// </summary>
-        AWSECSDetector,
+        AWSECS,
         /// <summary>
-        /// AWS EKS Resource Detector (OpenTelemetry.ResourceDetectors.AWS)
+        /// AWS EKS Resource Detector (OpenTelemetry.Resources.AWS)
         /// </summary>
-        AWSEKSDetector,
+        AWSEKS,
 
         /// <summary>
-        /// Azure App Service Resource Detector (OpenTelemetry.ResourceDetectors.Azure)
+        /// Azure App Service Resource Detector (OpenTelemetry.Resources.Azure)
         /// </summary>
-        AzureAppServiceDetector,
+        AzureAppService,
         /// <summary>
-        /// Azure Virtual Machine Resource Detector (OpenTelemetry.ResourceDetectors.Azure)
+        /// Azure Virtual Machine Resource Detector (OpenTelemetry.Resources.Azure)
         /// </summary>
-        AzureVMDetector,
+        AzureVM,
         /// <summary>
-        /// Azure Container Apps Resource Detector (OpenTelemetry.ResourceDetectors.Azure)
+        /// Azure Container Apps Resource Detector (OpenTelemetry.Resources.Azure)
         /// </summary>
-        AzureContainerAppsDetector,
+        AzureContainerApps,
 
         /// <summary>
-        /// Container Resource Detector (OpenTelemetry.ResourceDetectors.Container)
+        /// Container Resource Detector (OpenTelemetry.Resources.Container)
         /// </summary>
         Container,
 
         /// <summary>
-        /// Host Resource Detector (OpenTelemetry.ResourceDetectors.Host)
+        /// Host Resource Detector (OpenTelemetry.Resources.Host)
         /// </summary>
         Host,
 
         /// <summary>
-        /// Operating System Resource Detector (OpenTelemetry.ResourceDetectors.OperatingSystem)
+        /// Operating System Resource Detector (OpenTelemetry.Resources.OperatingSystem)
         /// </summary>
         OperatingSystem,
 
         /// <summary>
-        /// Process Resource Detector (OpenTelemetry.ResourceDetectors.Process)
+        /// Process Resource Detector (OpenTelemetry.Resources.Process)
         /// </summary>
         Process,
 
         /// <summary>
-        /// Process Runtime Resource Detector (OpenTelemetry.ResourceDetectors.ProcessRuntime)
+        /// Process Runtime Resource Detector (OpenTelemetry.Resources.ProcessRuntime)
         /// </summary>
         ProcessRuntime
     }

tests/Grafana.OpenTelemetry.Tests/ResourceDetectorTest.cs

@@ -17,12 +17,12 @@ public void EnumMatchesInitializers()
         {
             var expected = new HashSet<ResourceDetector>((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);