Every step is a span.

A host reports what its actors did as OpenTelemetry: a span for each step, logs, and metrics. It does no I/O itself. Your exporter sends the bytes.

See a traceTurn it on

Read a trace.

This payment charges a card, retries after 30 seconds of silence, and gives up after three attempts.

payment.scxml
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
       datamodel="ecmascript" name="payment" initial="charging">
  <datamodel><data id="attempts" expr="0"/></datamodel>
  <state id="charging">
    <onentry>
      <assign location="attempts" expr="attempts + 1"/>
      <send type="urn:payments" event="charge" target="card">
        <param name="attempt" expr="attempts"/>
      </send>
      <send event="timeout" delay="30s" id="timer"/>
    </onentry>
    <transition event="charged" target="paid"><cancel sendid="timer"/></transition>
    <transition event="timeout" cond="attempts &lt; 3" target="charging"/>
    <transition event="timeout" target="failed"/>
  </state>
  <final id="paid"><donedata><param name="outcome" expr="'paid'"/></donedata></final>
  <final id="failed"><donedata><param name="outcome" expr="'failed'"/></donedata></final>
</scxml>

Run it, traced, while the service is silent once and then answers. Each row is a step, under the step that caused it. Select one to see its transitions and what it sent.

Turn it on.

Give the host an encoder in its config and a handler for the requests it writes. The handler gets OTLP bytes, ready to post to a collector. This one reads the spans back.

telemetry.mjsjavascript
import { compileCharts, decodeTraces, Host, SimulatedClock } from '@tinyactors/node';

const compiled = compileCharts([{ name: 'order.scxml', text: `
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
       datamodel="ecmascript" name="order" initial="open">
  <state id="open">
    <transition event="pay" target="paid"><log label="order" expr="'paid'"/></transition>
  </state>
  <final id="paid"/>
</scxml>` }]);

const requests = [];
const clock = new SimulatedClock();
const host = new Host(compiled, {
  system: 'shop',
  config: {
    system: { ticksPerSecond: 1000 },                                        // the host's clock in milliseconds
    telemetry: { flushInterval: 1000, resource: { 'service.name': 'shop' } }, // a request at most a second after its first record
  },
  clock,
  telemetry: (signal, data) => {
    // A real exporter posts the bytes, from a promise so the host goes on:
    // fetch(`${collector}/v1/${signal}`, { method: 'POST', headers: { 'content-type': 'application/x-protobuf' }, body: data })
    requests.push([signal, data]);
  },
});
compiled.close();

const caller = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'; // a W3C traceparent, from an HTTP header
host.spawn('order').send('pay', undefined, { traceparent: caller });
await host.idle();
console.log('requests before the flush interval:', requests.length);
clock.increment(1000);
await host.idle();
console.log('signals:', requests.map(([signal]) => signal).sort().join(', '));

// Read the spans back (for a test; a collector does this for you).
for (const [signal, data] of requests) {
  if (signal !== 'traces') continue;
  const spans = decodeTraces(data);
  const ours = spans.filter((span) => span.trace === '0af7651916cd43dd8448eb211c80319c');
  console.log('spans in the caller\'s trace:', ours.map((span) => span.name).sort().join(', '));
  const step = ours.find((span) => span.name === 'scxml.macrostep pay');
  console.log('the step\'s parent is the caller\'s span:', step.parent === 'b7ad6b7169203331');
}
host.close();
output
requests before the flush interval: 0
signals: logs, traces
spans in the caller's trace: scxml.destroyed, scxml.finished, scxml.macrostep pay, scxml.microstep pay
the step's parent is the caller's span: true

Tune the encoder.

KeyDefaultWhat it does
flushInterval0a request is ready this long after its first record, in the host's clock ticks (system.ticksPerSecond); 0 means only when the staging is full, or at close
resourcenoneattributes on every request, such as service.name (at most 32, text to text)
logstrue<log> lines and failed actions as log records
valuesfalseevent data and assigned values in the spans; they may hold personal data, so turn this on knowingly
linkParentsfalsean actor's step is a root span linked to its cause, instead of its child
stagingBytes1048576the encoder's staging memory

Follow a request.

A traceparent passed with an input is the parent of the step it starts. A send carries the sender's trace to the next actor, or to another system.

context.mjsjavascript
import { compileCharts, Host } from '@tinyactors/node';

const compiled = compileCharts([{ name: 'c.scxml', text: `
<scxml xmlns="http://www.w3.org/2005/07/scxml" version="1.0"
       datamodel="ecmascript" name="c" initial="s">
  <state id="s">
    <transition event="go"><send type="urn:example:api" event="call"/></transition>
  </state>
</scxml>` }]);
const host = new Host(compiled, {
  system: 'demo',
  ioProcessors: {
    'urn:example:api': {
      receive(send) {
        const [, trace] = send.traceparent.split('-');
        console.log('the outgoing request continues trace', trace);
        // fetch(url, { headers: { traceparent: send.traceparent } })
      },
    },
  },
});
compiled.close();
host.spawn('c').send('go', undefined, {
  traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
});
await host.idle();
host.close();
output
the outgoing request continues trace 4bf92f3577b34da6a3ce929d0e0e4736

Choose what is traced.

Set the detail for every actor, or watch one chart closely for a while.

watch.mjsjavascript
import { Host } from '@tinyactors/node';

const host = new Host([], { system: 'shop', config: { telemetry: {} } });
await host.traceConfigure({ detail: 'summary', sample: 0.01 });
console.log('1 trace in 100, summarized');
const watch = await host.traceWatch({ rules: [{ chart: 'checkout', sample: 'keep', detail: 'full' }], seconds: 60 });
console.log(`watch ${watch.id}: every checkout in full for a minute`);
host.close();
output
1 trace in 100, summarized
watch 1: every checkout in full for a minute