Distributed Tracing

Understanding the path of a request as it moves through your Orchestrix workflows and into other services.

Why Tracing?

In a microservices architecture, a single flow might call multiple services. If one step is slow, you need to know if the slowness is in Orchestrix itself, in the network, or in the downstream service.

Integration with OpenTelemetry

Orchestrix's Hooks make it easy to integrate with OpenTelemetry.

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('orchestrix-instrumentation');

const flow = create("traced-flow", {
  hooks: {
    onFlowStart: (event) => {
      const span = tracer.startSpan(`Flow: ${event.flowName}`);
      event.context.set('flow_span', span);
    },
    onStepStart: (event) => {
      const parentSpan = event.context.get('flow_span');
      const stepSpan = tracer.startSpan(`Step: ${event.stepName}`, {
        links: [{ context: parentSpan.spanContext() }]
      });
      event.context.set(`span:${event.stepName}`, stepSpan);
    },
    onStepComplete: (event) => {
      const stepSpan = event.context.get(`span:${event.stepName}`);
      stepSpan.end();
    },
    onFlowComplete: (event) => {
      const flowSpan = event.context.get('flow_span');
      flowSpan.setStatus({ code: SpanStatusCode.OK });
      flowSpan.end();
    }
  }
});

Propagating Context

If your steps make HTTP calls, you should propagate the trace context to the next service so the spans can be linked.

.step("call-service-b", async (ctx) => {
  const span = ctx.get('span:call-service-b');
  const headers = {};
  // Inject span context into headers
  propagation.inject(context.active(), headers);
  await axios.get('...', { headers });
})

Benefits

• Visualizing Workflow Path: See exactly how long each step takes in a Gantt chart.
• Root Cause Analysis: Quickly identify which service in a Saga failed and triggered the compensation chain.
• Service Dependency Mapping: Automatically generate maps of which services your workflows depend on.