[OTLP] Add support for GZip compression (#7055)

Co-authored-by: Hannah Haering <157852144+hannahhaering@users.noreply.github.com>

Author: martincostello

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/.publicApi/Stable/PublicAPI.Unshipped.txt

@@ -0,0 +1,6 @@
+#nullable enable
+OpenTelemetry.Exporter.OtlpExportCompression
+OpenTelemetry.Exporter.OtlpExportCompression.GZip = 1 -> OpenTelemetry.Exporter.OtlpExportCompression
+OpenTelemetry.Exporter.OtlpExportCompression.None = 0 -> OpenTelemetry.Exporter.OtlpExportCompression
+OpenTelemetry.Exporter.OtlpExporterOptions.Compression.get -> OpenTelemetry.Exporter.OtlpExportCompression
+OpenTelemetry.Exporter.OtlpExporterOptions.Compression.set -> void

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/CHANGELOG.md

@@ -10,6 +10,11 @@ Notes](../../RELEASENOTES.md).
 * Fixed `NullReferenceException` when exporting logs if the scope key is null.
   ([#7186](https://github.com/open-telemetry/opentelemetry-dotnet/pull/7186))
 
+* Added opt-in support for gzip compression. Compression can be configured
+  programmatically via the new `OtlpExporterOptions.Compression` property,
+  or through the environment variables such as `OTEL_EXPORTER_OTLP_COMPRESSION=gzip`.
+  ([#7055](https://github.com/open-telemetry/opentelemetry-dotnet/issues/7055))
+
 ## 1.15.3
 
 Released 2026-Apr-21

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/IOtlpExporterOptions.cs

@@ -103,4 +103,9 @@ internal interface IOtlpExporterOptions
     /// </list>
     /// </remarks>
     Func<HttpClient> HttpClientFactory { get; set; }
+
+    /// <summary>
+    /// Gets or sets the compression method to use when sending telemetry.
+    /// </summary>
+    OtlpExportCompression Compression { get; set; }
 }

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/ExportClient/OtlpExportClient.cs

@@ -44,6 +44,7 @@ protected OtlpExportClient(OtlpExporterOptions options, HttpClient httpClient, s
         this.Endpoint = new UriBuilder(exporterEndpoint).Uri;
         this.Headers = options.GetHeaders<Dictionary<string, string>>((d, k, v) => d.Add(k, v));
         this.HttpClient = httpClient;
+        this.CompressionEnabled = options.Compression == OtlpExportCompression.GZip;
     }
 
     internal HttpClient HttpClient { get; }
@@ -52,6 +53,8 @@ protected OtlpExportClient(OtlpExporterOptions options, HttpClient httpClient, s
 
     internal IReadOnlyDictionary<string, string> Headers { get; }
 
+    internal bool CompressionEnabled { get; }
+
     internal abstract MediaTypeHeaderValue MediaTypeHeader { get; }
 
     internal virtual bool RequireHttp2 => false;
@@ -88,14 +91,25 @@ protected HttpRequestMessage CreateHttpRequest(byte[] buffer, int contentLength)
             request.Headers.Add(header.Key, header.Value);
         }
 
-        // TODO: Support compression.
-
-        request.Content = new ByteArrayContent(buffer, 0, contentLength);
-        request.Content.Headers.ContentType = this.MediaTypeHeader;
+        request.Content = this.CreateHttpContent(buffer, contentLength);
 
         return request;
     }
 
+    /// <summary>
+    /// Creates the <see cref="HttpContent"/> for a request. Override in subclasses to
+    /// customise content creation (e.g. to apply compression).
+    /// </summary>
+    /// <param name="buffer">The serialized protobuf payload buffer.</param>
+    /// <param name="contentLength">The number of bytes within <paramref name="buffer"/> that make up the message.</param>
+    /// <returns>An <see cref="HttpContent"/> representing the export payload.</returns>
+    protected virtual HttpContent CreateHttpContent(byte[] buffer, int contentLength)
+    {
+        var content = new ByteArrayContent(buffer, 0, contentLength);
+        content.Headers.ContentType = this.MediaTypeHeader;
+        return content;
+    }
+
     protected HttpResponseMessage SendHttpRequest(HttpRequestMessage request, CancellationToken cancellationToken) =>
 #if NET
         // Note: SendAsync must be used with HTTP/2 because synchronous send is

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/ExportClient/OtlpGrpcExportClient.cs

@@ -4,8 +4,11 @@
 #if NETFRAMEWORK
 using System.Net.Http;
 #endif
+using System.Buffers.Binary;
 using System.Diagnostics.Tracing;
+using System.IO.Compression;
 using System.Net.Http.Headers;
+using System.Net.Sockets;
 using OpenTelemetry.Exporter.OpenTelemetryProtocol.Implementation.ExportClient.Grpc;
 
 namespace OpenTelemetry.Exporter.OpenTelemetryProtocol.Implementation.ExportClient;
@@ -14,6 +17,12 @@ namespace OpenTelemetry.Exporter.OpenTelemetryProtocol.Implementation.ExportClie
 internal sealed class OtlpGrpcExportClient : OtlpExportClient
 {
     public const string GrpcStatusDetailsHeader = "grpc-status-details-bin";
+
+    // A gRPC message frame header is 5 bytes:
+    //   byte 0     - Compression flag (0 = not compressed, 1 = compressed).
+    //   bytes 1-4  - Message length in big-endian format.
+    private const int GrpcMessageHeaderSize = 5;
+
     private static readonly ExportClientHttpResponse SuccessExportResponse = new(success: true, deadlineUtc: default, response: null, exception: null);
     private static readonly MediaTypeHeaderValue MediaHeaderValue = new("application/grpc");
 
@@ -25,6 +34,10 @@ private static readonly ExportClientGrpcResponse DefaultExceptionExportClientGrp
             status: null,
             grpcStatusDetailsHeader: null);
 
+#if !NET
+    private static readonly byte[] GrpcFrameHeader = [0, 0, 0, 0, 0];
+#endif
+
     public OtlpGrpcExportClient(OtlpExporterOptions options, HttpClient httpClient, string signalPath)
         : base(options, httpClient, signalPath)
     {
@@ -37,6 +50,11 @@ public OtlpGrpcExportClient(OtlpExporterOptions options, HttpClient httpClient,
     // We need the entire response content to ensure that the response trailers are received
     internal override HttpCompletionOption CompletionOption => HttpCompletionOption.ResponseContentRead;
 
+#if NET
+    // See https://vcsjones.dev/csharp-readonly-span-bytes-static/
+    private static ReadOnlySpan<byte> GrpcFrameHeader => [0, 0, 0, 0, 0];
+#endif
+
     /// <inheritdoc/>
     public override ExportClientResponse SendExportRequest(byte[] buffer, int contentLength, DateTime deadlineUtc, CancellationToken cancellationToken = default)
     {
@@ -50,6 +68,12 @@ public override ExportClientResponse SendExportRequest(byte[] buffer, int conten
             // A missing TE header results in servers aborting the gRPC call.
             httpRequest.Headers.TryAddWithoutValidation("TE", "trailers");
 
+            if (this.CompressionEnabled)
+            {
+                httpRequest.Headers.Remove("grpc-encoding");
+                httpRequest.Headers.TryAddWithoutValidation("grpc-encoding", "gzip");
+            }
+
             httpResponse = this.SendHttpRequest(httpRequest, cancellationToken);
 
             httpResponse.EnsureSuccessStatusCode();
@@ -173,10 +197,54 @@ public override ExportClientResponse SendExportRequest(byte[] buffer, int conten
         }
     }
 
+    protected override HttpContent CreateHttpContent(byte[] buffer, int contentLength)
+    {
+        if (!this.CompressionEnabled)
+        {
+            return base.CreateHttpContent(buffer, contentLength);
+        }
+
+        // Build a gzip-compressed gRPC message frame:
+        //   byte 0     - Compression flag = 1 (gzip).
+        //   bytes 1-4  - Compressed payload length in big-endian format.
+        //   bytes 5+   - Gzip-compressed protobuf payload.
+#if NET
+        var compressedStream = new PooledBufferStream();
+#else
+        var compressedStream = new MemoryStream();
+#endif
+
+        // Reserve space for the gRPC frame header.
+#if NET
+        compressedStream.Write(GrpcFrameHeader);
+#else
+        compressedStream.Write(GrpcFrameHeader, 0, GrpcFrameHeader.Length);
+#endif
+
+        using (var gzipStream = new GZipStream(compressedStream, CompressionLevel.Fastest, leaveOpen: true))
+        {
+            gzipStream.Write(buffer, GrpcMessageHeaderSize, contentLength - GrpcMessageHeaderSize);
+        }
+
+        var compressedPayloadLength = (uint)(compressedStream.Length - GrpcMessageHeaderSize);
+
+        // Write the gRPC frame header: compression flag + big-endian payload length.
+        compressedStream.Position = 0;
+        compressedStream.WriteByte(1);
+
+        var lengthBytes = new byte[4];
+        BinaryPrimitives.WriteUInt32BigEndian(lengthBytes, compressedPayloadLength);
+        compressedStream.Write(lengthBytes, 0, 4);
+
+        compressedStream.Position = 0;
+
+        OpenTelemetryProtocolExporterEventSource.Log.CompressedGrpcPayload("gzip", contentLength, compressedStream.Length);
+
+        var content = new StreamContent(compressedStream);
+        content.Headers.ContentType = this.MediaTypeHeader;
+        return content;
+    }
+
     private static bool IsTransientNetworkError(HttpRequestException ex) =>
-        ex.InnerException is System.Net.Sockets.SocketException socketEx
-        && (socketEx.SocketErrorCode == System.Net.Sockets.SocketError.TimedOut
-            || socketEx.SocketErrorCode == System.Net.Sockets.SocketError.ConnectionReset
-            || socketEx.SocketErrorCode == System.Net.Sockets.SocketError.HostUnreachable
-            || socketEx.SocketErrorCode == System.Net.Sockets.SocketError.ConnectionRefused);
+        ex.InnerException is SocketException { SocketErrorCode: SocketError.TimedOut or SocketError.ConnectionReset or SocketError.HostUnreachable or SocketError.ConnectionRefused };
 }

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/ExportClient/OtlpHttpExportClient.cs

@@ -5,6 +5,7 @@
 using System.Net.Http;
 #endif
 using System.Diagnostics.Tracing;
+using System.IO.Compression;
 using System.Net.Http.Headers;
 
 namespace OpenTelemetry.Exporter.OpenTelemetryProtocol.Implementation.ExportClient;
@@ -54,4 +55,34 @@ public override ExportClientResponse SendExportRequest(byte[] buffer, int conten
             return new ExportClientHttpResponse(success: false, deadlineUtc: deadlineUtc, response: null, exception: ex);
         }
     }
+
+    protected override HttpContent CreateHttpContent(byte[] buffer, int contentLength)
+    {
+        if (!this.CompressionEnabled)
+        {
+            return base.CreateHttpContent(buffer, contentLength);
+        }
+
+#if NET
+        var compressedStream = new PooledBufferStream();
+#else
+        var compressedStream = new MemoryStream();
+#endif
+
+        using (var gzipStream = new GZipStream(compressedStream, CompressionLevel.Fastest, leaveOpen: true))
+        {
+            gzipStream.Write(buffer, 0, contentLength);
+        }
+
+        compressedStream.Position = 0;
+
+        OpenTelemetryProtocolExporterEventSource.Log.CompressedHttpPayload("gzip", contentLength, compressedStream.Length);
+
+        var content = new StreamContent(compressedStream);
+
+        content.Headers.ContentType = this.MediaTypeHeader;
+        content.Headers.Add("Content-Encoding", "gzip");
+
+        return content;
+    }
 }