Feature: Telemetry and Observability

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/telemetry.ts
• config/config.example.json
• apps/runtime/crates/core/Cargo.toml
• apps/runtime/crates/core/examples/improved.rs
• README.md
• apps/api/package.json

The Kodus Runtime project incorporates a comprehensive telemetry and observability system built on OpenTelemetry (OTEL). This allows for the collection of distributed traces and metrics from both the Node.js API (kodus-api) and the core Rust runtime (kodus-runtime), providing deep insights into system performance, request lifecycles, and error rates. The system is designed to export this data to any OTLP-compatible backend for analysis and visualization.

The implementation is split between the two main application components. The Node.js API has a dedicated TelemetryService for handling HTTP request tracing and metrics. The Rust core's telemetry capabilities are enabled via a feature flag (otel) and configured through the central config.json file, which also governs the API's telemetry settings.

Sources: README.md:12, config/config.example.json:30-37

Architecture Overview

The telemetry architecture consists of two primary sources of data: the Node.js API and the Rust Runtime. Both are configured to send telemetry data (traces and metrics) via the OTLP gRPC protocol to a configurable endpoint, typically an OpenTelemetry Collector.

Sources: apps/api/src/telemetry.ts:38-41, 62-65, config/config.example.json:31-32

This diagram illustrates the flow of telemetry data from the application components to an OTLP collector.

Configuration

Telemetry for both the Rust runtime and the Node.js API is controlled via the telemetry section in the main config.json file. The Node.js API also reads the OTLP endpoint from the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.

Sources: config/config.example.json:30-37, apps/api/src/telemetry.ts:39, 63

Parameter	Type	Description	Default Value
enabled	boolean	Master switch to enable or disable telemetry for the Rust runtime.	false
endpoint	string	The OTLP endpoint URL for both Rust and Node.js components.	http://localhost:4318
service_name	string	The service name identifier for the Rust runtime.	kodus-runtime
service_version	string	The service version for the Rust runtime.	0.1.0
metrics_enabled	boolean	Enables or disables the collection of metrics.	true
tracing_enabled	boolean	Enables or disables the collection of traces.	true

Sources: config/config.example.json:30-37

Node.js API Telemetry (kodus-api)

The API's telemetry is managed by the TelemetryService class, which provides a singleton instance for application-wide use. It leverages OpenTelemetry SDKs to configure and manage tracers and meters.

Sources: apps/api/src/telemetry.ts:12, 203

Core Components

The TelemetryService class encapsulates all logic for initializing telemetry, creating spans, and recording metrics.

This diagram shows the structure of the TelemetryService class and its main components.

Tracing

Distributed tracing is implemented via an Express-style middleware. For each incoming HTTP request, the createRequestMiddleware function initiates a new span named http_request. This span is automatically populated with relevant attributes.

• http.method: The HTTP request method (e.g., GET, POST).
• http.url: The full request URL.
• http.route: The matched route path.
• user.id: The authenticated user's ID, if available.
• http.status_code: The response status code.

The span's status is set to ERROR for status codes 400 and above.

Sources: apps/api/src/telemetry.ts:153-178

The following sequence diagram shows the lifecycle of a traced HTTP request.

Metrics

The service automatically collects several key metrics for all HTTP requests:

Metric Name	Type	Description	Labels
http_requests_total	Counter	Total number of HTTP requests.	method, path, status_code
http_request_duration_seconds	Histogram	Duration of HTTP requests in seconds.	method, path, status_code
http_requests_errors_total	Counter	Total number of HTTP request errors (status >= 400).	method, path, status_code

These metrics are exported periodically (every 30 seconds) to the configured OTLP endpoint.

Sources: apps/api/src/telemetry.ts:72-91, 137-148

Initialization

The TelemetryService is initialized with the service name kodus-api. It sets up a NodeTracerProvider and a MeterProvider, both configured to export data using OTLPTraceExporter and OTLPMetricExporter respectively. The endpoint is sourced from process.env.OTEL_EXPORTER_OTLP_ENDPOINT or defaults to http://localhost:4317.

// apps/api/src/telemetry.ts:38-41
const traceExporter = new OTLPTraceExporter({
  url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
  headers: {},
})

Sources: apps/api/src/telemetry.ts:28-70

Rust Core Telemetry (kodus-runtime)

Telemetry in the Rust core is an optional feature that can be enabled during compilation.

Enabling Telemetry

To include telemetry capabilities, the kodus-core crate must be compiled with the otel feature flag. This flag includes the necessary OpenTelemetry dependencies.

# apps/runtime/crates/core/Cargo.toml:9-15
[features]
default       = ["async-runtime"]
async-runtime  = ["dep:tokio"]
fiber         = ["dep:may"]
otel          = [
  "tracing",
  "tracing-subscriber",
  "opentelemetry_sdk",
  "opentelemetry-otlp",
  "tracing-opentelemetry"
]

Sources: apps/runtime/crates/core/Cargo.toml:9-15

Initialization

The telemetry system is initialized by calling a function within the telemetry module, which reads its configuration from the telemetry section of config.json. An example demonstrates this initialization process.

// apps/runtime/crates/core/examples/improved.rs:24-31
#[cfg(feature = "otel")]
{
    use kodus_core::telemetry;
    if let Err(e) = telemetry::init(&config.telemetry) {
        eprintln!("⚠️  Falha ao iniciar telemetria: {}", e);
    } else {
        println!("✅ Telemetria inicializada");
    }
}

This snippet shows that if the otel feature is enabled, a telemetry::init function is called with the configuration object. This sets up the tracing and metrics pipeline for the Rust runtime.

Sources: apps/runtime/crates/core/examples/improved.rs:24-31

Summary

The telemetry and observability feature in Kodus Runtime provides a powerful, unified solution for monitoring the entire system. By leveraging OpenTelemetry, it offers a standardized way to collect, export, and analyze traces and metrics from both the high-level Node.js API and the low-level Rust core. The flexible configuration allows developers to easily integrate it into various monitoring backends, making it an essential feature for maintaining system health and diagnosing issues in production environments.

Sources: README.md:12, apps/api/src/telemetry.ts, config/config.example.json:30-37