• English

      • Telemetry

      Note

      This feature is currently experimental.

      NocoBase's Telemetry module is encapsulated based on OpenTelemetry, used for collecting Trace and Metric data to enhance the observability of NocoBase.

      Instrumentation

      Metrics

      const meter = app.telemetry.metric.getMeter();
const counter = meter.createCounter('event_counter', {});
counter.add(1);

      For detailed usage, see OpenTelemetry - Acquiring a Meter.

      Traces

      const tracer = app.telemetry.trace.getTracer();
tracer.startActiveSpan();
tracer.startSpan();

      For detailed usage, see OpenTelemetry - Acquiring a Tracer.

      Libraries

      import { Plugin } from '@nocobase/server';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

class InstrumentationPlugin extends Plugin {
  afterAdd() {
    this.app.on('beforeLoad', (app) => {
      app.telemetry.addInstrumentation(getNodeAutoInstrumentations());
    });
  }
}
      Note

      In NocoBase, the initialization location of the telemetry module is app.beforeLoad. Therefore, not all instrumentation libraries are suitable for NocoBase. For example, instrumentation-koa needs to be introduced before Koa is instantiated, but although NocoBase's Application is based on Koa, the telemetry module is initialized after the Application is instantiated, so it cannot be used.

      For detailed usage, see OpenTelemetry - Libraries.

      Collection

      Metrics

      import { Plugin } from '@nocobase/server';
import {
  PeriodicExportingMetricReader,
  ConsoleMetricExporter,
} from '@opentelemetry/sdk-metrics';

class MetricReaderPlugin extends Plugin {
  afterAdd() {
    this.app.on('beforeLoad', (app) => {
      app.telemetry.metric.registerReader(
        'console',
        () =>
          new PeriodicExportingMetricReader({
            exporter: new ConsoleMetricExporter(),
          }),
      );
    });
  }
}

      Traces

      import { Plugin } from '@nocobase/server';
import {
  BatchSpanProcessor,
  ConsoleSpanExporter,
} from '@opentelemetry/sdk-trace-base';

class TraceSpanProcessorPlugin extends Plugin {
  afterAdd() {
    this.app.on('beforeLoad', (app) => {
      app.telemetry.trace.registerProcessor(
        'console',
        () => new BatchSpanProcessor(new ConsoleSpanExporter()),
      );
    });
  }
}

      For detailed usage, see OpenTelemetry - Exporters.

      • Logger — Using logging alongside telemetry for a complete observability solution
      • Plugin — Register telemetry instrumentation and collectors in plugins
      • Server Development Overview — The position of the telemetry module in server architecture
      • Event — Initialize telemetry in beforeLoad through the event mechanism
      • Middleware — Combine telemetry with middleware for request tracing