Custom Tracers ¶

Stario's telemetry system is extensible. You can build custom tracers to send logs to external services (Datadog, Honeycomb) or local files.

1. Implement the Protocol ¶

A tracer must implement three methods: open(), close(), and submit().

from stario.telemetry import Tracer, Trace

class FileTracer:
    def open(self):
        self.file = open("traces.jsonl", "a")

    def close(self):
        self.file.close()

    def submit(self, trace: Trace):
        # trace.trace_id: unique ID
        # trace.spans: list of steps
        self.file.write(f"{trace.trace_id} - {len(trace.spans)} spans\n")
        self.file.flush()

2. Register the Tracer ¶

Pass your custom tracer when initializing the Stario app.

app = Stario(tracer=FileTracer())

3. Composite Tracers ¶

You can use multiple tracers at once (e.g., console for dev + JSON for prod).

class MultiTracer:
    def __init__(self, *tracers):
        self.tracers = tracers

    def open(self):
        [t.open() for t in self.tracers]

    def close(self):
        [t.close() for t in self.tracers]

    def submit(self, trace: Trace):
        [t.submit(trace) for t in self.tracers]

app = Stario(tracer=MultiTracer(RichTracer(), FileTracer()))

Best Practices ¶

• Fast submit(): The submit() method is called synchronously. If you are sending data to a slow external API, use asyncio.create_task() or a background queue inside submit().
• Error Handling: Don't let tracer errors crash your main application. Wrap your submit() logic in a try/except.