For Scientists & Developers

This section covers everything you need to instrument a scientific pipeline with HelixObs.

What you need to know

HelixObs revolves around two ideas:

Entities are data products — anything your pipeline creates, transforms, or consumes. Each entity has a stable string ID chosen by you (a database key, a filename, a UUID). The ID follows the entity across every pipeline stage, compute node, and instrument.

Provenance is the graph of which entities produced which. You declare parent IDs when creating an entity; the herald — the HelixObs server your client connects to — assembles these into a queryable DAG stored in TimescaleDB and visualised in Grafana.

The herald is invisible to your code: you configure its address once in helixobs.setup() and the client library handles the rest. See Core Concepts for a full explanation of what it does.

Pages in this section

Core Concepts	Entities, tokens, operations, the provenance DAG
Installation	pip install, optional dependencies
Tracking Entities	Three integration layers: Token API, context manager, decorator
Structured Logging	Two delivery modes — sidecar (Alloy) and OTLP — and what each requires
Authentication	Connecting to a herald that requires credentials
API Reference	Full reference for setup(), Instrument, Token

Quick orientation

helixobs.setup()          ← start here; returns an Instrument
  │
  ├── Instrument.create()     ← new entity coming into existence
  ├── Instrument.operate()    ← work on an existing entity
  ├── Instrument.track()      ← context manager shorthand (create + operate)
  └── Instrument.stage()      ← decorator shorthand
          │
          └── Token
                ├── .start()
                ├── .complete(metadata={...})
                ├── .error(message)
                └── .add_event(name, metadata={...})