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.
Read a trace.
This payment charges a card, retries after 30 seconds of silence, and gives up after three attempts.
<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 < 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.
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();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: trueTune the encoder.
| Key | Default | What it does |
|---|---|---|
flushInterval | 0 | a 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 |
resource | none | attributes on every request, such as service.name (at most 32, text to text) |
logs | true | <log> lines and failed actions as log records |
values | false | event data and assigned values in the spans; they may hold personal data, so turn this on knowingly |
linkParents | false | an actor's step is a root span linked to its cause, instead of its child |
stagingBytes | 1048576 | the 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.
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();the outgoing request continues trace 4bf92f3577b34da6a3ce929d0e0e4736Choose what is traced.
Set the detail for every actor, or watch one chart closely for a while.
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();1 trace in 100, summarized
watch 1: every checkout in full for a minute