Skip to main content

Quik Framework :: telemetry

Integrates OpenTelemetry into the framework with optional logging bridge support.

Installation​

npm install @quik/telemetry

Usage​

1) Register the module​

import { Module as Telemetry } from "@quik/telemetry";

await Telemetry.setup({} as any);

2) Configure the exporter and enable telemetry​

TELEMETRY_ENABLED=true
TELEMETRY_SERVICE_NAME=quik-app
TELEMETRY_AUTO_INSTRUMENTATIONS=true
TELEMETRY_OTLP_ENDPOINT=https://collector:4318/v1/traces

3) (Optional) Bridge logs into the active span​

TELEMETRY_LOGGING_BRIDGE=true
TELEMETRY_LOGGING_PASSTHROUGH=true

4) Start spans manually (feature API)​

import { getTelemetry } from "@quik/telemetry";

const telemetry = getTelemetry();
telemetry?.withSpan("jobs.run", async () => {
  // do work
});

5) Use decorators to trace methods​

import { TelemetryDecorators } from "@quik/telemetry";

class JobsService {
  @TelemetryDecorators.Span("jobs.process")
  async process() {
    // do work
  }
}

Configuration​

Environment overrides:

  • TELEMETRY_ENABLED
  • TELEMETRY_SERVICE_NAME
  • TELEMETRY_AUTO_INSTRUMENTATIONS
  • TELEMETRY_OTLP_ENDPOINT
  • TELEMETRY_LOGGING_BRIDGE
  • TELEMETRY_LOGGING_PASSTHROUGH

API Highlights​

  • QTelemetry OpenTelemetry bootstrapper with start()/shutdown().
  • TelemetryLogger bridges logs to active spans and can pass through to the existing logger.
  • getTelemetry() returns the telemetry feature instance when enabled.
  • TelemetryDecorators.Span() wraps method execution in a telemetry span.

Module Integrations​

When telemetry is enabled, the following modules emit spans:

  • HTTP: wraps the request pipeline for each endpoint.
  • Scheduler: wraps each task execution.
  • Communication: wraps provider send operations.

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the telemetry API section.