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

index.mddocs/

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

docs

index.md

tile.json