CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-opentelemetry--exporter-metrics-otlp-proto

OpenTelemetry Collector Metrics Exporter that sends collected metrics to the OpenTelemetry Collector using protobuf over HTTP

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

OpenTelemetry Metrics Exporter (Protobuf)

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.

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

Package Information

  • Package Name: @opentelemetry/exporter-metrics-otlp-proto
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @opentelemetry/exporter-metrics-otlp-proto

Core Imports

import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";

For CommonJS:

const { OTLPMetricExporter } = require("@opentelemetry/exporter-metrics-otlp-proto");

Basic Usage

import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";

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

// Set up meter provider with exporter
const meterProvider = new MeterProvider({
  readers: [
    new PeriodicExportingMetricReader({
      exporter: metricExporter,
      exportIntervalMillis: 1000,
    }),
  ],
});

// Start recording data
const meter = meterProvider.getMeter("example-meter");
const counter = meter.createCounter("metric_name");
counter.add(10, { key: "value" });

Capabilities

Metric Export

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

class OTLPMetricExporter extends OTLPMetricExporterBase implements PushMetricExporter {
  // Platform-specific constructor signatures:
  // Node.js: config is optional
  constructor(config?: OTLPExporterNodeConfigBase & OTLPMetricExporterOptions);
  
  // Inherited from OTLPMetricExporterBase and PushMetricExporter
  export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void;
  selectAggregationTemporality(instrumentType: InstrumentType): AggregationTemporality;
  selectAggregation(instrumentType: InstrumentType): AggregationOption;
  shutdown(): Promise<void>;
  forceFlush(): Promise<void>;
}

Configuration Options

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

interface OTLPExporterNodeConfigBase extends OTLPExporterConfigBase {
  keepAlive?: boolean;
  compression?: CompressionAlgorithm;
  httpAgentOptions?: http.AgentOptions | https.AgentOptions | HttpAgentFactory;
}

interface OTLPExporterConfigBase {
  headers?: Record<string, string>;
  url?: string;
  concurrencyLimit?: number;
  timeoutMillis?: number;
}

interface OTLPMetricExporterOptions extends OTLPExporterConfigBase {
  temporalityPreference?: AggregationTemporalityPreference | AggregationTemporality;
  aggregationPreference?: AggregationSelector;
}

enum AggregationTemporality {
  DELTA,
  CUMULATIVE,
}

enum AggregationTemporalityPreference {
  DELTA,
  CUMULATIVE,
  LOWMEMORY,
}

enum CompressionAlgorithm {
  NONE = 'none',
  GZIP = 'gzip',
}

Aggregation and Temporality Selection

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

type AggregationSelector = (instrumentType: InstrumentType) => AggregationOption;
type AggregationTemporalitySelector = (instrumentType: InstrumentType) => AggregationTemporality;

enum InstrumentType {
  COUNTER = 'COUNTER',
  GAUGE = 'GAUGE',
  HISTOGRAM = 'HISTOGRAM',
  UP_DOWN_COUNTER = 'UP_DOWN_COUNTER',
  OBSERVABLE_COUNTER = 'OBSERVABLE_COUNTER',
  OBSERVABLE_GAUGE = 'OBSERVABLE_GAUGE',
  OBSERVABLE_UP_DOWN_COUNTER = 'OBSERVABLE_UP_DOWN_COUNTER',
}

type AggregationOption = 
  | ExponentialHistogramAggregationOption
  | HistogramAggregationOption
  | SumAggregationOption
  | DropAggregationOption
  | DefaultAggregationOption
  | LastValueAggregationOption;

Types

interface PushMetricExporter {
  export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void;
  forceFlush(): Promise<void>;
  selectAggregationTemporality?(instrumentType: InstrumentType): AggregationTemporality;
  selectAggregation?(instrumentType: InstrumentType): AggregationOption;
  shutdown(): Promise<void>;
}

interface ExportResult {
  code: ExportResultCode;
  error?: Error;
}

enum ExportResultCode {
  SUCCESS,
  FAILED,
}

interface ResourceMetrics {
  resource: Resource;
  scopeMetrics: ScopeMetrics[];
}

interface ScopeMetrics {
  scope: InstrumentationScope;
  metrics: MetricData[];
}

interface Resource {
  attributes: Record<string, any>;
}

interface InstrumentationScope {
  name: string;
  version?: string;
}

interface MetricData {
  descriptor: InstrumentDescriptor;
  aggregationTemporality: AggregationTemporality;
  dataPointType: DataPointType;
  dataPoints: DataPoint[];
}

interface InstrumentDescriptor {
  readonly name: string;
  readonly description?: string;
  readonly unit?: string;
  readonly type: InstrumentType;
  readonly valueType: ValueType;
}

enum DataPointType {
  SUM,
  GAUGE,
  HISTOGRAM,
  EXPONENTIAL_HISTOGRAM,
}

enum ValueType {
  INT,
  DOUBLE,
}

type DataPoint = NumberDataPoint | HistogramDataPoint | ExponentialHistogramDataPoint;

interface NumberDataPoint {
  attributes: MetricAttributes;
  startTime: HrTime;
  endTime: HrTime;
  value: number;
}

interface HistogramDataPoint {
  attributes: MetricAttributes;
  startTime: HrTime;
  endTime: HrTime;
  count: number;
  sum?: number;
  min?: number;
  max?: number;
  buckets: HistogramBucket[];
}

interface ExponentialHistogramDataPoint {
  attributes: MetricAttributes;
  startTime: HrTime;
  endTime: HrTime;
  count: number;
  sum?: number;
  min?: number;
  max?: number;
  scale: number;
  zeroCount: number;
  positive: ExponentialHistogramBuckets;
  negative: ExponentialHistogramBuckets;
}

type MetricAttributes = Record<string, any>;
type HrTime = [number, number];

Platform-Specific Behavior

Node.js Environment

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

Browser Environment

  • Uses XMLHttpRequest or fetch API via legacy browser export delegate
  • Supports sendBeacon API for improved reliability during page unload
  • Handles CORS requirements for cross-origin requests
  • Content-Type: application/x-protobuf
  • Constructor parameter is required (defaults to empty object)

Built-in Temporality Selectors

The package provides three built-in temporality selectors:

const CumulativeTemporalitySelector: AggregationTemporalitySelector;
const DeltaTemporalitySelector: AggregationTemporalitySelector;
const LowMemoryTemporalitySelector: AggregationTemporalitySelector;

Error Handling

Export operations may fail with various error conditions:

  • Network connectivity issues
  • Invalid endpoint URLs
  • Authentication failures
  • Collector unavailability
  • Serialization errors

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

Environment Variables

The exporter supports standard OpenTelemetry environment variables for configuration:

VariableDescriptionDefault
OTEL_EXPORTER_OTLP_ENDPOINTBase endpoint URLhttp://localhost:4318
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTMetrics-specific endpointhttp://localhost:4318/v1/metrics

Requirements

  • Node.js: ^18.19.0 || >=20.6.0
  • OpenTelemetry API: ^1.3.0
  • Modern browser with XMLHttpRequest or fetch support

Dependencies

The exporter extends functionality from these OpenTelemetry packages:

  • @opentelemetry/exporter-metrics-otlp-http: Base HTTP metrics exporter
  • @opentelemetry/otlp-exporter-base: Common OTLP functionality
  • @opentelemetry/otlp-transformer: Protobuf serialization
  • @opentelemetry/sdk-metrics: Metrics SDK integration

Install with Tessl CLI

npx tessl i tessl/npm-opentelemetry--exporter-metrics-otlp-proto
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@opentelemetry/exporter-metrics-otlp-proto@0.204.x
Publish Source
CLI
Badge
tessl/npm-opentelemetry--exporter-metrics-otlp-proto badge