HTTP API

API Endpoints

The Tram service provides the following HTTP endpoints:

Method	Endpoint	Description
GET	/v1/streams	List all streams, ordered by name
PUT	/v1/streams/{name}	Create or update a stream
GET	/v1/streams/{name}	Get a stream configuration
DELETE	/v1/streams/{name}	Delete a stream
GET	/metrics	Metrics of Tram in the Prometheus format, see Metrics

The stream name is taken from the URL; a name in the request body is replaced by it.

Updating a Stream

A PUT to an existing stream changes as little as possible:

Change	Effect
None	Nothing happens; the running stream is kept
Stages, sinks or metrics only	The new stages and sinks are created, events still in flight finish in the old ones, and the source switches over. The source keeps running, e.g. an OTLP source keeps its port open, and no event is lost
Source	The stream is stopped and created again. An OTLP source closes its port in between, so clients briefly cannot connect

If an update fails, e.g. because of an invalid component spec, the request returns an error and the previous version of the stream keeps running. Delete and create a stream to restart it completely.

If the source of a stream stops on its own, e.g. because its NATS stream does not exist yet, Tram restarts the stream after a delay that grows from 1 second to 1 minute while it keeps failing. A PUT of the unchanged stream restarts it right away.