0
# gRPC Exporters
1

2
OTLP exporters using gRPC protocol with protobuf serialization. These exporters provide efficient binary protocol communication with OpenTelemetry Collector endpoints, offering high performance and built-in load balancing capabilities.
3

4
## Capabilities
5

6
### Span Exporter (gRPC)
7

8
Exports distributed tracing data using the gRPC protocol. Supports streaming and efficient batch export of span data to OpenTelemetry Collector endpoints.
9

10
```python { .api }
11
class OTLPSpanExporter:
12
    def __init__(
13
        self,
14
        endpoint: str | None = None,
15
        insecure: bool | None = None,
16
        credentials: grpc.ChannelCredentials | None = None,
17
        headers: dict[str, str] | None = None,
18
        timeout: float | None = None,
19
        compression: grpc.Compression | None = None,
20
        channel_options: list[tuple[str, str]] | None = None
21
    ):
22
        """
23
        Create a gRPC OTLP span exporter.
24

25
        Parameters:
26
        - endpoint (str, optional): Collector endpoint URL. Defaults to "localhost:4317"
27
        - insecure (bool, optional): Use insecure connection. Defaults to True for localhost
28
        - credentials (grpc.ChannelCredentials, optional): gRPC channel credentials for secure connections
29
        - headers (dict, optional): Additional headers to send with requests
30
        - timeout (int, optional): Export timeout in seconds. Defaults to 10
31
        - compression (grpc.Compression, optional): gRPC compression algorithm
32
        - channel_options (list, optional): Additional gRPC channel options
33

34
        Environment Variables:
35
        - OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
36
        - OTEL_EXPORTER_OTLP_TRACES_HEADERS
37
        - OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
38
        - OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
39
        """
40

41
    def export(self, spans) -> SpanExportResult:
42
        """Export span data to the collector."""
43

44
    def shutdown(self, timeout_millis: int = 30000) -> bool:
45
        """Shutdown the exporter and clean up resources."""
46

47
    def force_flush(self, timeout_millis: int = 30000) -> bool:
48
        """Force flush any pending spans."""
49
```
50

51
### Metric Exporter (gRPC)
52

53
Exports metrics data using the gRPC protocol. Provides efficient transmission of measurement data with support for different temporality preferences and batch size limits.
54

55
```python { .api }
56
class OTLPMetricExporter:
57
    def __init__(
58
        self,
59
        endpoint: str | None = None,
60
        insecure: bool | None = None,
61
        credentials: grpc.ChannelCredentials | None = None,
62
        headers: dict[str, str] | None = None,
63
        timeout: float | None = None,
64
        compression: grpc.Compression | None = None,
65
        preferred_temporality: dict | None = None,
66
        preferred_aggregation: dict | None = None,
67
        max_export_batch_size: int | None = None,
68
        channel_options: list[tuple[str, str]] | None = None
69
    ):
70
        """
71
        Create a gRPC OTLP metric exporter.
72

73
        Parameters:
74
        - endpoint (str, optional): Collector endpoint URL. Defaults to "localhost:4317"
75
        - insecure (bool, optional): Use insecure connection. Defaults to True for localhost
76
        - credentials (grpc.ChannelCredentials, optional): gRPC channel credentials for secure connections
77
        - headers (dict, optional): Additional headers to send with requests
78
        - timeout (int, optional): Export timeout in seconds. Defaults to 10
79
        - compression (grpc.Compression, optional): gRPC compression algorithm
80
        - preferred_temporality (dict, optional): Preferred temporality for metric instruments
81
        - preferred_aggregation (dict, optional): Preferred aggregation for metric instruments
82
        - max_export_batch_size (int, optional): Maximum number of metrics per export batch
83
        - channel_options (list, optional): Additional gRPC channel options
84

85
        Environment Variables:
86
        - OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
87
        - OTEL_EXPORTER_OTLP_METRICS_HEADERS
88
        - OTEL_EXPORTER_OTLP_METRICS_TIMEOUT
89
        - OTEL_EXPORTER_OTLP_METRICS_COMPRESSION
90
        """
91

92
    def export(self, metrics) -> MetricExportResult:
93
        """Export metric data to the collector."""
94

95
    def shutdown(self, timeout_millis: int = 30000) -> bool:
96
        """Shutdown the exporter and clean up resources."""
97

98
    def force_flush(self, timeout_millis: int = 30000) -> bool:
99
        """Force flush any pending metrics."""
100
```
101

102
### Log Exporter (gRPC)
103

104
Exports structured log data using the gRPC protocol. Enables efficient transmission of log records with full OpenTelemetry context correlation.
105

106
```python { .api }
107
class OTLPLogExporter:
108
    def __init__(
109
        self,
110
        endpoint: str | None = None,
111
        insecure: bool | None = None,
112
        credentials: grpc.ChannelCredentials | None = None,
113
        headers: dict[str, str] | None = None,
114
        timeout: float | None = None,
115
        compression: grpc.Compression | None = None,
116
        channel_options: list[tuple[str, str]] | None = None
117
    ):
118
        """
119
        Create a gRPC OTLP log exporter.
120

121
        Parameters:
122
        - endpoint (str, optional): Collector endpoint URL. Defaults to "localhost:4317"
123
        - insecure (bool, optional): Use insecure connection. Defaults to True for localhost
124
        - credentials (grpc.ChannelCredentials, optional): gRPC channel credentials for secure connections
125
        - headers (dict, optional): Additional headers to send with requests
126
        - timeout (int, optional): Export timeout in seconds. Defaults to 10
127
        - compression (grpc.Compression, optional): gRPC compression algorithm
128
        - channel_options (list, optional): Additional gRPC channel options
129

130
        Environment Variables:
131
        - OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
132
        - OTEL_EXPORTER_OTLP_LOGS_HEADERS
133
        - OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
134
        - OTEL_EXPORTER_OTLP_LOGS_COMPRESSION
135
        """
136

137
    def export(self, logs) -> LogExportResult:
138
        """Export log data to the collector."""
139

140
    def shutdown(self, timeout_millis: int = 30000) -> bool:
141
        """Shutdown the exporter and clean up resources."""
142

143
    def force_flush(self, timeout_millis: int = 30000) -> bool:
144
        """Force flush any pending logs."""
145
```
146

147
### Base Exporter Mixin
148

149
```python { .api }
150
class OTLPExporterMixin:
151
    """
152
    Generic base class providing common OTLP gRPC export functionality.
153
    
154
    This mixin provides shared functionality for all gRPC-based OTLP exporters,
155
    including configuration parsing, channel setup, and common export logic.
156
    """
157
    
158
    def _configure_exporter(self, **kwargs) -> None:
159
        """Configure the exporter with provided parameters and environment variables."""
160
    
161
    def _export(self, serialized_data: bytes, path: str) -> bool:
162
        """Export serialized data to the configured endpoint."""
163

164
    def _shutdown(self) -> None:
165
        """Clean up resources used by the exporter."""
166
```
167

168
## Utility Functions
169

170
### Compression Conversion
171

172
```python { .api }
173
def environ_to_compression(compression: str) -> grpc.Compression:
174
    """
175
    Convert environment variable compression value to gRPC Compression enum.
176

177
    Parameters:
178
    - compression (str): Compression algorithm name ("gzip", "deflate", or "none")
179

180
    Returns:
181
    grpc.Compression: Corresponding gRPC compression enum value
182

183
    Raises:
184
    ValueError: If compression algorithm is not supported
185
    """
186
```
187

188
### Credential Loading
189

190
```python { .api }
191
def _get_credentials(
192
    insecure: bool = None,
193
    credentials: grpc.ChannelCredentials = None
194
) -> grpc.ChannelCredentials:
195
    """
196
    Load SSL credentials from environment variables or provided parameters.
197

198
    Parameters:
199
    - insecure (bool, optional): Whether to use insecure connection
200
    - credentials (grpc.ChannelCredentials, optional): Pre-configured credentials
201

202
    Returns:
203
    grpc.ChannelCredentials: Channel credentials for secure connections
204

205
    Environment Variables:
206
    - OTEL_EXPORTER_OTLP_CERTIFICATE
207
    - OTEL_EXPORTER_OTLP_CLIENT_KEY
208
    - OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE
209
    """
210
```
211

212
## Usage Examples
213

214
### Basic gRPC Export Setup
215

216
```python
217
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
218
from opentelemetry.sdk.trace import TracerProvider
219
from opentelemetry.sdk.trace.export import BatchSpanProcessor
220

221
# Create exporter with default settings
222
exporter = OTLPSpanExporter()
223

224
# Set up tracer provider with batch processor
225
tracer_provider = TracerProvider()
226
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
227

228
# Use the tracer
229
tracer = tracer_provider.get_tracer(__name__)
230
with tracer.start_as_current_span("example-span"):
231
    print("Hello, World!")
232
```
233

234
### Secure gRPC Connection
235

236
```python
237
import grpc
238
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
239

240
# Create secure credentials
241
credentials = grpc.ssl_channel_credentials(
242
    root_certificates=None,  # Use system's root certificates
243
    private_key=None,
244
    certificate_chain=None
245
)
246

247
# Create exporter with secure connection
248
exporter = OTLPSpanExporter(
249
    endpoint="https://my-collector:4317",
250
    credentials=credentials,
251
    headers={"api-key": "your-api-key"},
252
    compression=grpc.Compression.Gzip
253
)
254
```
255

256
### Environment Variable Configuration
257

258
```python
259
import os
260

261
# Set environment variables
262
os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = "https://collector:4317"
263
os.environ["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] = "api-key=your-key"
264
os.environ["OTEL_EXPORTER_OTLP_TRACES_COMPRESSION"] = "gzip"
265

266
# Create exporter - will automatically use environment variables
267
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
268
exporter = OTLPSpanExporter()
269
```
270

271
## Constants
272

273
```python { .api }
274
# Default gRPC channel options
275
_OTLP_GRPC_CHANNEL_OPTIONS: list = [
276
    ("grpc.user_agent", "opentelemetry-python"),
277
    # Additional channel configuration options
278
]
279
```