Setup & Usage

The DomusJS Observability Module leverages OpenTelemetry, providing comprehensive access to its ecosystem.

Key Features:

• OpenTelemetry-Compliant Instrumentations: Easily integrate with HTTP, DB, gRPC, and more.
• Custom Middleware: Implement middleware for enhanced tracing, metrics, and logging.
• Extensible Exporters: Seamlessly extend with exporters like SigNoz, Datadog, Jaeger, and Prometheus.

This setup is easy to customize and expand, making it suitable for practical monitoring needs.

---

Setup the Tracer

import { setupObservability, getDefaultConfig } from '@domusjs/observability';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';

setupObservability({
  config: {
    ...getDefaultConfig('domusjs-app'),
    traceExporter: new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces',
    }),
  },
  instrumentations: [
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ],
});

✅ This initializes OpenTelemetry with your desired exporters and instrumentations.

---

Use the @Traceable Decorator

The @Traceable decorator automatically creates a tracing span for a method, tracking execution time, attributes, and events.

import { Traceable } from '@domusjs/observability';

class UserService {
  @Traceable({ spanName: 'user.create' })
  async createUser(data: any) {
    // Logic here
  }
}

✅ Automatically creates spans when the decorated method is called.

You can also pass advanced options.

---

📄 TraceableOptions Explained

The TraceableOptions type offers fine-grained control over how spans are named and enriched.

Option	Description
spanName	Custom name for the span. Defaults to ClassName.methodName.
attributes	Function returning a map of attributes derived from method arguments.
logEvent	String or function generating an event name to log before execution.
resultAttributes	Function returning attributes derived from the method’s result.
resultEvent	Function returning an event name to log after execution completes.

Example with all options

@Traceable({
  spanName: 'user.register',
  attributes: (args) => ({ userId: args[0]?.id }),
  logEvent: 'Starting user registration',
  resultAttributes: (result) => ({ success: result.success }),
  resultEvent: (result) => result.success ? 'User registered' : 'User registration failed',
})
async registerUser(userData) {
  // ...
}

✅ This enriches the trace with dynamic data from both input and output.

---

Manually Trace Code

import { traceFn } from '@domusjs/observability';

await traceFn('my-operation', async (span) => {
  span.setAttribute('custom.attribute', 'value');
  // ... your logic here
});

✅ For advanced cases where you want full control over the span boundaries.

---

Use OpenTelemetryLogger

Setup the logger with the registerDomusCore function.

import { registerDomusCore } from '@domusjs/infrastructure';
import { OpenTelemetryLogger } from '@domusjs/observability';

registerDomusCore({
  logger: new OpenTelemetryLogger(
    'http://localhost:4318/v1/logs', // OTLP log exporter URL
    'domusjs-app'                   // service name
  ),
});

✅ This logger automatically injects trace context (traceId, spanId) into your logs, improving cross-correlation between traces and logs.

---

🌍 Understanding OTLP URLs

The OpenTelemetry Protocol (OTLP) is the standard used by OpenTelemetry to send telemetry data, including traces, metrics, and logs, to collectors or observability backends such as SigNoz, Datadog, or Jaeger.

In DomusJS, you configure the OTLP endpoints during the setup of exporters.

---

📡 Common Endpoints

Data Type	Default OTLP Path
Traces	http://<collector-host>:4318/v1/traces
Logs	http://<collector-host>:4318/v1/logs
Metrics	http://<collector-host>:4318/v1/metrics (if used)

✅ Example: If you are running SigNoz locally:

• Traces: http://localhost:4318/v1/traces
• Logs: http://localhost:4318/v1/logs