Deprecate use of GRAFANA_CLOUD_* environment variables in code and documentation (#87)

* Deprecate GRAFANA_CLOUD_ environment variables

* Remove obsolete tests

* Fix warnings

* Add changelog

* Linter issues

* Linter fixes

Author: pyohannes

CHANGELOG.md

@@ -9,6 +9,19 @@
 * [#85](https://github.com/grafana/grafana-opentelemetry-dotnet/pull/85)
   Adds resource detectors for Azure, host, process, process runtime, and
   container resource attributes.
+* [#87](https://github.com/grafana/grafana-opentelemetry-dotnet/pull/87)
+  Add a new `OtlpExporter` class supporting specifying OTLP protocol, endpoint,
+  and header
+
+### Deprecation
+
+* [#87](https://github.com/grafana/grafana-opentelemetry-dotnet/pull/87)
+  Deprecate use of `GRAFANA_CLOUD_*` environment variables in code and documentation
+
+  The use of `CloudOtlpExporter` and `GRAFANA_CLOUD_*` environment variables is
+  deprecated. Instead use `OtlpExporter` for code-level configuration, and
+  `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_ENDPOINT`, and
+  `OTEL_EXPORTER_OTLP_HEADERS` for configuration via environment variables.
 
 ## 0.7.0-beta.3
 

README.md

@@ -42,35 +42,25 @@ The `UseGrafana` extension method on the `TracerProviderBuilder` or the
 default, telemetry data will be sent to a Grafana agent or an OTel collector
 that runs locally and listens to default OTLP ports.
 
-Given the zone, instance ID, and API token, telemetry data can be sent directly
-to the Grafana Cloud without involving an agent or collector:
-
 ```csharp
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
-    .UseGrafana(config =>
-    {
-        config.ExporterSettings = new CloudOtlpExporter
-        {
-            Zone = "prod-us-east-0",
-            InstanceId = "123456",
-            ApiKey = "a-secret-token"
-        };
-    })
+    .UseGrafana()
     .Build();
 ```
 
-For details on how to obtain those values, refer to [Sending data directly to
-Grafana Cloud via
-OTLP](./docs/configuration.md#sending-data-directly-to-grafana-cloud-via-otlp).
+Alternatively, you can send telemetry data directly to Grafana Cloud without
+involving an agent or collector. This can be configured via the environment
+variables `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_ENDPOINT`, and
+`OTEL_EXPORTER_OTLP_HEADERS`.
 
-Alternatively, these values can be set via the environment variables
-`GRAFANA_CLOUD_ZONE`, `GRAFANA_CLOUD_INSTANCE_ID`, and
-`GRAFANA_CLOUD_API_KEY`.
+For details on how to obtain those values, refer to [Push directly from
+applications using the OpenTelemetry
+SDKs](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/#push-directly-from-applications-using-the-opentelemetry-sdks).
 
 ```sh
-export GRAFANA_CLOUD_ZONE=prod-us-east-0
-export GRAFANA_CLOUD_INSTANCE_ID=123456
-export GRAFANA_CLOUD_API_KEY=a-secret-token
+export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
+export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic a-secret-token"
 ```
 
 ## Documentation

docs/configuration.md

@@ -121,35 +121,30 @@ to the Grafana Cloud without involving an agent or collector:
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .UseGrafana(config =>
     {
-        config.ExporterSettings = new CloudOtlpExporter
+        config.ExporterSettings = new OtlpExporter
         {
-            Zone = "prod-us-east-0",
-            InstanceId = "123456",
-            ApiKey = "a-secret-token"
+            Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf,
+            Endpoint = Uri("https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"),
+            Headers = "Authorization=Basic a-secret-token"
         };
     })
     .Build();
 ```
 
-Follow the following steps to obtain the zone, instance id, and an API token:
-
-1. Click **Details** in the **Grafana** section on
-   <https://grafana.com/profile/org>.
-2. You will see values for **Instance ID** and **Zone** on this page.
-3. On the left menu, click on **Security** and then on **API Keys**
-4. Obtain a new API token by clicking on **Create API Key** (`MetricsPublisher`
-   role).
-
 Alternatively, these values can be set via the environment variables
-`GRAFANA_CLOUD_ZONE`, `GRAFANA_CLOUD_INSTANCE_ID`, and
-`GRAFANA_CLOUD_API_KEY`.
+`OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_ENDPOINT`, and
+`OTEL_EXPORTER_OTLP_HEADERS`.
 
 ```sh
-export GRAFANA_CLOUD_ZONE=prod-us-east-0
-export GRAFANA_CLOUD_INSTANCE_ID=123456
-export GRAFANA_CLOUD_API_KEY=a-secret-token
+export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
+export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic a-secret-token"
 ```
 
+For details on how to obtain those values, refer to [Push directly from
+applications using the OpenTelemetry
+SDKs](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/#push-directly-from-applications-using-the-opentelemetry-sdks).
+
 ## Instrumentation configuration
 
 ### Disabling instrumentations
@@ -314,6 +309,3 @@ 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_CLOUD_ZONE`                      | "prod-us-east-0"     | Zone of the Grafana Cloud stack to send data to. |
-| `GRAFANA_CLOUD_INSTANCE_ID`               | "123456"             | Instance ID of the Grafana Cloud stack to send data to. |
-| `GRAFANA_CLOUD_API_KEY`                   |                      | API key of the Grafana Cloud Stack to send data to. |

src/Grafana.OpenTelemetry.Base/ExporterSettings/CloudOtlpExporter.cs

@@ -15,6 +15,7 @@ namespace Grafana.OpenTelemetry
     /// <summary>
     /// Settings for exporting telemetry directly to Grafana Agent via OTLP.
     /// </summary>
+    [Obsolete("This class is obsolete. Use OtlpExporter instead.")]
     public class CloudOtlpExporter : ExporterSettings
     {
         internal const string ZoneEnvVarName = "GRAFANA_CLOUD_ZONE";

src/Grafana.OpenTelemetry.Base/ExporterSettings/OtlpExporter.cs

@@ -0,0 +1,85 @@
+//
+// Copyright Grafana Labs
+// SPDX-License-Identifier: Apache-2.0
+//
+
+using System;
+using Microsoft.Extensions.Configuration;
+using OpenTelemetry.Exporter;
+using OpenTelemetry.Logs;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Trace;
+
+namespace Grafana.OpenTelemetry
+{
+    /// <summary>
+    /// Settings for exporting telemetry via plain OTLP exporter settings.
+    /// </summary>
+    public class OtlpExporter : ExporterSettings
+    {
+        /// <summary>
+        /// Gets or sets the target to which the exporter is going to send telemetry.
+        /// Must be a valid Uri with scheme (http or https) and host, and
+        /// may contain a port and path.
+        /// </summary>
+        public Uri Endpoint { get; set; }
+
+        /// <summary>
+        /// Gets or sets optional headers for the connection. Refer to the <a href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#specifying-headers-via-environment-variables">specification</a> for information on the expected format for Headers.
+        /// </summary>
+        public string Headers { get; set; }
+
+        /// <summary>
+        /// Gets or sets the the OTLP transport protocol. Supported values: Grpc and HttpProtobuf
+        /// </summary>
+        public OtlpExportProtocol Protocol { get; set; }
+
+        /// <inheritdoc/>
+        override internal void Apply(TracerProviderBuilder builder)
+        {
+            if (EnableTraces == false)
+            {
+                return;
+            }
+
+            builder.AddOtlpExporter(config =>
+            {
+                config.Endpoint = new Uri($"{Endpoint}/v1/traces");
+                config.Headers = Headers;
+                config.Protocol = Protocol;
+            });
+        }
+
+        /// <inheritdoc/>
+        override internal void Apply(MeterProviderBuilder builder)
+        {
+            if (EnableMetrics == false)
+            {
+                return;
+            }
+
+            builder.AddOtlpExporter(config =>
+            {
+                config.Endpoint = new Uri($"{Endpoint}/v1/metrics");
+                config.Headers = Headers;
+                config.Protocol = Protocol;
+            });
+        }
+
+        /// <inheritdoc/>
+        override internal void Apply(OpenTelemetryLoggerOptions options)
+        {
+            if (EnableLogs == false)
+            {
+                return;
+            }
+
+            options.AddOtlpExporter(config =>
+            {
+                config.Endpoint = new Uri($"{Endpoint}/v1/logs");
+                config.Headers = Headers;
+                config.Protocol = Protocol;
+            });
+        }
+    }
+}

src/Grafana.OpenTelemetry.Base/GrafanaOpenTelemetrySettings.cs

@@ -89,7 +89,9 @@ internal GrafanaOpenTelemetrySettings(IConfiguration configuration)
         {
             try
             {
+#pragma warning disable CS0618
                 ExporterSettings = new CloudOtlpExporter();
+#pragma warning restore CS0618
             }
             catch (Exception)
             {