0
# OpenTelemetry Protobuf Encoding
1

2
A convenience library for encoding OpenTelemetry telemetry data to Protocol Buffers (protobuf) format. This package serves as a common foundation for OTLP (OpenTelemetry Protocol) exporters, providing efficient encoding mechanisms for transforming OpenTelemetry SDK data structures into protobuf messages that can be transmitted to OpenTelemetry collectors and other OTLP-compatible telemetry backends.
3

4
## Package Information
5

6
- **Package Name**: opentelemetry-exporter-otlp-proto-common
7
- **Language**: Python
8
- **Installation**: `pip install opentelemetry-exporter-otlp-proto-common`
9

10
## Core Imports
11

12
```python
13
# Version information
14
from opentelemetry.exporter.otlp.proto.common import __version__
15

16
# Main encoding functions
17
from opentelemetry.exporter.otlp.proto.common.trace_encoder import encode_spans
18
from opentelemetry.exporter.otlp.proto.common.metrics_encoder import encode_metrics
19
from opentelemetry.exporter.otlp.proto.common._log_encoder import encode_logs
20
```
21

22
## Basic Usage
23

24
```python
25
from opentelemetry.exporter.otlp.proto.common.trace_encoder import encode_spans
26
from opentelemetry.exporter.otlp.proto.common.metrics_encoder import encode_metrics
27
from opentelemetry.exporter.otlp.proto.common._log_encoder import encode_logs
28

29
# Example: Encoding spans for trace export
30
from opentelemetry.sdk.trace import TracerProvider, Tracer
31
from opentelemetry.sdk.trace.export import ReadableSpan
32

33
# Assume you have a collection of spans from the OpenTelemetry SDK
34
spans = []  # List of ReadableSpan objects
35

36
# Encode spans to OTLP protobuf format
37
encoded_request = encode_spans(spans)
38

39
# The encoded_request can now be sent via gRPC or HTTP to an OTLP collector
40
```
41

42
## Capabilities
43

44
### Version Information
45

46
Access the package version for compatibility checking and debugging.
47

48
```python { .api }
49
__version__: str
50
```
51

52
### Trace Encoding
53

54
Encodes OpenTelemetry span data into OTLP protobuf format for transmission to trace collectors.
55

56
```python { .api }
57
def encode_spans(sdk_spans: Sequence[ReadableSpan]) -> PB2ExportTraceServiceRequest:
58
    """
59
    Encode a sequence of OpenTelemetry spans into OTLP protobuf format.
60
    
61
    Parameters:
62
    - sdk_spans: Sequence[ReadableSpan] - A sequence of span objects from the OpenTelemetry SDK
63
    
64
    Returns:
65
    - PB2ExportTraceServiceRequest - Protobuf message containing encoded trace data
66
    """
67
```
68

69
### Metrics Encoding
70

71
Encodes OpenTelemetry metrics data into OTLP protobuf format for transmission to metrics collectors.
72

73
```python { .api }
74
def encode_metrics(data: MetricsData) -> ExportMetricsServiceRequest:
75
    """
76
    Encode OpenTelemetry metrics data into OTLP protobuf format.
77
    
78
    Parameters:
79
    - data: MetricsData - OpenTelemetry metrics data object containing metrics to encode
80
    
81
    Returns:
82
    - ExportMetricsServiceRequest - Protobuf message containing encoded metrics data
83
    """
84
```
85

86
### Log Encoding
87

88
Encodes OpenTelemetry log data into OTLP protobuf format for transmission to log collectors.
89

90
```python { .api }
91
def encode_logs(batch: Sequence[LogData]) -> ExportLogsServiceRequest:
92
    """
93
    Encode a sequence of OpenTelemetry log records into OTLP protobuf format.
94
    
95
    Parameters:
96
    - batch: Sequence[LogData] - A sequence of log data objects from the OpenTelemetry SDK
97
    
98
    Returns:
99
    - ExportLogsServiceRequest - Protobuf message containing encoded log data
100
    """
101
```
102

103
## Types
104

105
```python { .api }
106
# Core types from OpenTelemetry SDK (imported for type references)
107
from typing import Sequence
108
from opentelemetry.sdk.trace import ReadableSpan
109
from opentelemetry.sdk.metrics.export import MetricsData
110
from opentelemetry.sdk._logs import LogData
111

112
# Protobuf message types (return types)
113
from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest as PB2ExportTraceServiceRequest
114
from opentelemetry.proto.collector.metrics.v1.metrics_service_pb2 import ExportMetricsServiceRequest
115
from opentelemetry.proto.collector.logs.v1.logs_service_pb2 import ExportLogsServiceRequest
116
```
117

118
## Error Handling
119

120
The encoding functions may raise exceptions during the encoding process. These are typically standard Python exceptions that occur during protobuf message construction or data validation.
121

122
## Dependencies
123

124
This package requires:
125
- `opentelemetry-proto == 1.36.0` - Protocol buffer definitions for OpenTelemetry
126

127
## Usage Context
128

129
This library is designed to be used internally by OTLP exporters including:
130
- `opentelemetry-exporter-otlp-proto-grpc` - gRPC transport for OTLP
131
- `opentelemetry-exporter-otlp-proto-http` - HTTP transport for OTLP
132

133
The encoding functions transform OpenTelemetry SDK data structures into protobuf messages that maintain compatibility with OpenTelemetry collectors and other OTLP-compatible telemetry backends, ensuring proper handling of semantic conventions and the OTLP protobuf schema.