NucliaDB Telemetry

6.13.0.post6185 verified Fri May 01 auth: no python

Telemetry library for NucliaDB processes. Provides OpenTelemetry-based tracing, metrics, and logging with Sentry integration. Current version 6.13.0.post6185, frequent releases.

pip install nucliadb-telemetry

Common errors

error ModuleNotFoundError: No module named 'opentelemetry' ↓

cause Missing optional dependency opentelemetry-api

fix

pip install nucliadb-telemetry[otel] # or pip install opentelemetry-api opentelemetry-sdk

error ImportError: cannot import name 'Telemetry' from 'nucliadb_telemetry' ↓

cause Wrong import path; Telemetry is not in a submodule but directly in package

fix

from nucliadb_telemetry import Telemetry

error TypeError: Telemetry.__init__() got an unexpected keyword argument 'log_level' ↓

cause Breaking change in v6.10.0: log_level moved to nested 'logging' dict

fix

Pass settings = {'logging': {'level': 'INFO'}} instead of {'log_level': 'INFO'}

Warnings

breaking Settings dict structure changed in v6.10.0: 'sentry_dsn' renamed from 'sentry_dsn' (remains same) but 'log_level' moved to a nested dict under 'logging'. Check changelog. ↓

fix Review settings dict: use 'logging': {'level': 'DEBUG'} instead of top-level 'log_level'.

gotcha Telemetry.setup() may block if Sentry DSN is set but unreachable. Network timeouts can delay startup. ↓

fix Consider setting SENTRY_DSN='' for local development, or run setup in background thread.

gotcha OpenTelemetry spans may not appear if no exporter is configured. The library defaults to a console exporter for debugging; production requires setting OTEL_EXPORTER_OTLP_ENDPOINT. ↓

fix Set env var OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 or configure in settings.

Imports

Telemetry

wrong

from nucliadb_telemetry.telemetry import Telemetry

correct

from nucliadb_telemetry import Telemetry

Public API is at package level, not submodule

utils

wrong

from nucliadb_telemetry.utils import some_func

correct

from nucliadb_telemetry import utils

utils is a module; import it, then access functions via utils.XXX

Quickstart

Initialize telemetry with Sentry and OpenTelemetry. Settings dict configures endpoints and service name.

import os
from nucliadb_telemetry import Telemetry

# Use environment variables for configuration
service_name = os.environ.get('SERVICE_NAME', 'my-service')
settings = {
    'sentry_dsn': os.environ.get('SENTRY_DSN', ''),
    'service_name': service_name,
}
telemetry = Telemetry(settings)
telemetry.setup()  # initializes tracing, metrics, logging