0
# OpenTelemetry Metrics Exporter (Protobuf)
1

2
OpenTelemetry Collector Metrics Exporter that sends collected metrics to the OpenTelemetry Collector using protobuf over HTTP. This exporter provides platform-specific implementations for both Node.js and browser environments, extending the base OTLP HTTP metrics functionality with protobuf serialization.
3

4
**Note: This is an experimental package under active development. New releases may include breaking changes.**
5

6
## Package Information
7

8
- **Package Name**: @opentelemetry/exporter-metrics-otlp-proto
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install @opentelemetry/exporter-metrics-otlp-proto`
12

13
## Core Imports
14

15
```typescript
16
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { OTLPMetricExporter } = require("@opentelemetry/exporter-metrics-otlp-proto");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
29
import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
30

31
// Create exporter with configuration
32
const metricExporter = new OTLPMetricExporter({
33
  url: "http://localhost:4318/v1/metrics", // Optional - defaults to localhost:4318
34
});
35

36
// Set up meter provider with exporter
37
const meterProvider = new MeterProvider({
38
  readers: [
39
    new PeriodicExportingMetricReader({
40
      exporter: metricExporter,
41
      exportIntervalMillis: 1000,
42
    }),
43
  ],
44
});
45

46
// Start recording data
47
const meter = meterProvider.getMeter("example-meter");
48
const counter = meter.createCounter("metric_name");
49
counter.add(10, { key: "value" });
50
```
51

52
## Capabilities
53

54
### Metric Export
55

56
Export collected metrics to an OpenTelemetry Collector using protobuf serialization over HTTP.
57

58
```typescript { .api }
59
class OTLPMetricExporter extends OTLPMetricExporterBase implements PushMetricExporter {
60
  // Platform-specific constructor signatures:
61
  // Node.js: config is optional
62
  constructor(config?: OTLPExporterNodeConfigBase & OTLPMetricExporterOptions);
63
  
64
  // Inherited from OTLPMetricExporterBase and PushMetricExporter
65
  export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void;
66
  selectAggregationTemporality(instrumentType: InstrumentType): AggregationTemporality;
67
  selectAggregation(instrumentType: InstrumentType): AggregationOption;
68
  shutdown(): Promise<void>;
69
  forceFlush(): Promise<void>;
70
}
71
```
72

73
### Configuration Options
74

75
The exporter accepts configuration options that combine base OTLP settings with metrics-specific options.
76

77
```typescript { .api }
78
interface OTLPExporterNodeConfigBase extends OTLPExporterConfigBase {
79
  keepAlive?: boolean;
80
  compression?: CompressionAlgorithm;
81
  httpAgentOptions?: http.AgentOptions | https.AgentOptions | HttpAgentFactory;
82
}
83

84
interface OTLPExporterConfigBase {
85
  headers?: Record<string, string>;
86
  url?: string;
87
  concurrencyLimit?: number;
88
  timeoutMillis?: number;
89
}
90

91
interface OTLPMetricExporterOptions extends OTLPExporterConfigBase {
92
  temporalityPreference?: AggregationTemporalityPreference | AggregationTemporality;
93
  aggregationPreference?: AggregationSelector;
94
}
95

96
enum AggregationTemporality {
97
  DELTA,
98
  CUMULATIVE,
99
}
100

101
enum AggregationTemporalityPreference {
102
  DELTA,
103
  CUMULATIVE,
104
  LOWMEMORY,
105
}
106

107
enum CompressionAlgorithm {
108
  NONE = 'none',
109
  GZIP = 'gzip',
110
}
111
```
112

113
### Aggregation and Temporality Selection
114

115
The exporter provides methods for selecting aggregation strategies and temporality preferences for different instrument types.
116

117
```typescript { .api }
118
type AggregationSelector = (instrumentType: InstrumentType) => AggregationOption;
119
type AggregationTemporalitySelector = (instrumentType: InstrumentType) => AggregationTemporality;
120

121
enum InstrumentType {
122
  COUNTER = 'COUNTER',
123
  GAUGE = 'GAUGE',
124
  HISTOGRAM = 'HISTOGRAM',
125
  UP_DOWN_COUNTER = 'UP_DOWN_COUNTER',
126
  OBSERVABLE_COUNTER = 'OBSERVABLE_COUNTER',
127
  OBSERVABLE_GAUGE = 'OBSERVABLE_GAUGE',
128
  OBSERVABLE_UP_DOWN_COUNTER = 'OBSERVABLE_UP_DOWN_COUNTER',
129
}
130

131
type AggregationOption = 
132
  | ExponentialHistogramAggregationOption
133
  | HistogramAggregationOption
134
  | SumAggregationOption
135
  | DropAggregationOption
136
  | DefaultAggregationOption
137
  | LastValueAggregationOption;
138
```
139

140
## Types
141

142
```typescript { .api }
143
interface PushMetricExporter {
144
  export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void;
145
  forceFlush(): Promise<void>;
146
  selectAggregationTemporality?(instrumentType: InstrumentType): AggregationTemporality;
147
  selectAggregation?(instrumentType: InstrumentType): AggregationOption;
148
  shutdown(): Promise<void>;
149
}
150

151
interface ExportResult {
152
  code: ExportResultCode;
153
  error?: Error;
154
}
155

156
enum ExportResultCode {
157
  SUCCESS,
158
  FAILED,
159
}
160

161
interface ResourceMetrics {
162
  resource: Resource;
163
  scopeMetrics: ScopeMetrics[];
164
}
165

166
interface ScopeMetrics {
167
  scope: InstrumentationScope;
168
  metrics: MetricData[];
169
}
170

171
interface Resource {
172
  attributes: Record<string, any>;
173
}
174

175
interface InstrumentationScope {
176
  name: string;
177
  version?: string;
178
}
179

180
interface MetricData {
181
  descriptor: InstrumentDescriptor;
182
  aggregationTemporality: AggregationTemporality;
183
  dataPointType: DataPointType;
184
  dataPoints: DataPoint[];
185
}
186

187
interface InstrumentDescriptor {
188
  readonly name: string;
189
  readonly description?: string;
190
  readonly unit?: string;
191
  readonly type: InstrumentType;
192
  readonly valueType: ValueType;
193
}
194

195
enum DataPointType {
196
  SUM,
197
  GAUGE,
198
  HISTOGRAM,
199
  EXPONENTIAL_HISTOGRAM,
200
}
201

202
enum ValueType {
203
  INT,
204
  DOUBLE,
205
}
206

207
type DataPoint = NumberDataPoint | HistogramDataPoint | ExponentialHistogramDataPoint;
208

209
interface NumberDataPoint {
210
  attributes: MetricAttributes;
211
  startTime: HrTime;
212
  endTime: HrTime;
213
  value: number;
214
}
215

216
interface HistogramDataPoint {
217
  attributes: MetricAttributes;
218
  startTime: HrTime;
219
  endTime: HrTime;
220
  count: number;
221
  sum?: number;
222
  min?: number;
223
  max?: number;
224
  buckets: HistogramBucket[];
225
}
226

227
interface ExponentialHistogramDataPoint {
228
  attributes: MetricAttributes;
229
  startTime: HrTime;
230
  endTime: HrTime;
231
  count: number;
232
  sum?: number;
233
  min?: number;
234
  max?: number;
235
  scale: number;
236
  zeroCount: number;
237
  positive: ExponentialHistogramBuckets;
238
  negative: ExponentialHistogramBuckets;
239
}
240

241
type MetricAttributes = Record<string, any>;
242
type HrTime = [number, number];
243
```
244

245
## Platform-Specific Behavior
246

247
### Node.js Environment
248
- Uses Node.js HTTP client for requests
249
- Sets User-Agent header with library version: `OTel-OTLP-Exporter-JavaScript/{VERSION}`
250
- Supports all Node.js networking features (proxies, custom agents, etc.)
251
- Content-Type: `application/x-protobuf`
252
- Constructor parameter is optional
253

254
### Browser Environment  
255
- Uses XMLHttpRequest or fetch API via legacy browser export delegate
256
- Supports sendBeacon API for improved reliability during page unload
257
- Handles CORS requirements for cross-origin requests
258
- Content-Type: `application/x-protobuf`
259
- Constructor parameter is required (defaults to empty object)
260

261
## Built-in Temporality Selectors
262

263
The package provides three built-in temporality selectors:
264

265
```typescript { .api }
266
const CumulativeTemporalitySelector: AggregationTemporalitySelector;
267
const DeltaTemporalitySelector: AggregationTemporalitySelector;
268
const LowMemoryTemporalitySelector: AggregationTemporalitySelector;
269
```
270

271
## Error Handling
272

273
Export operations may fail with various error conditions:
274

275
- Network connectivity issues
276
- Invalid endpoint URLs
277
- Authentication failures
278
- Collector unavailability
279
- Serialization errors
280

281
Failed exports are reported through the result callback with appropriate error codes and messages.
282

283
## Environment Variables
284

285
The exporter supports standard OpenTelemetry environment variables for configuration:
286

287
| Variable | Description | Default |
288
|----------|-------------|---------|
289
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base endpoint URL | `http://localhost:4318` |
290
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Metrics-specific endpoint | `http://localhost:4318/v1/metrics` |
291
292
## Requirements
293

294
- Node.js: ^18.19.0 || >=20.6.0
295
- OpenTelemetry API: ^1.3.0
296
- Modern browser with XMLHttpRequest or fetch support
297

298
## Dependencies
299

300
The exporter extends functionality from these OpenTelemetry packages:
301
- `@opentelemetry/exporter-metrics-otlp-http`: Base HTTP metrics exporter
302
- `@opentelemetry/otlp-exporter-base`: Common OTLP functionality  
303
- `@opentelemetry/otlp-transformer`: Protobuf serialization
304
- `@opentelemetry/sdk-metrics`: Metrics SDK integration