# sensorium

Observability for agents: OpenTelemetry in, MCP out.

## What it is

sensorium keeps the logs, traces and metrics of many services in one Postgres store and serves them to agents over MCP. There is no dashboard: the reader is an agent doing maintenance or analysis. It is open source under the MIT License.

## What it does

- **Ingest**: OpenTelemetry over HTTP, as JSON or protobuf, at `/v1/logs`, `/v1/traces` and `/v1/metrics`.
- **Projects**: Each project has its own ingest token, and the token decides where its records land.
- **MCP**: Eight read-only tools at `/mcp`: `list_projects`, `query_logs`, `query_traces`, `list_traces`, `error_summary`, `top_sources`, `query_metrics` and `search`.
- **Retention**: Metrics for 14 days, spans and logs for 30, by default.

## Deploy

1. On any machine with Docker, fetch the compose file and the env example. Set `POSTGRES_PASSWORD` and `SENSORIUM_MCP_TOKEN` in `.env`.

   ```sh
   curl -fsSLO https://raw.githubusercontent.com/zyx1121/sensorium/main/compose.yaml
   curl -fsSL -o .env https://raw.githubusercontent.com/zyx1121/sensorium/main/.env.example
   ```

2. Start it. The receiver on port 8787, the MCP endpoint on port 8788 and a daily retention sweep come up from one image, beside Postgres.

   ```sh
   docker compose up -d
   ```

3. Put a reverse proxy with TLS in front, and route `/mcp` to port 8788 and everything else to port 8787. Both ports listen on 127.0.0.1, and tokens travel in the Authorization header.

## Use

1. Register a project. The token is printed once, and running it again for the same name rotates it.

   ```sh
   docker compose run --rm ingest register-project my-service
   ```

2. Point the service's OpenTelemetry exporter at sensorium. sensorium takes neither gzip nor gRPC. For an exporter that only speaks those, put an OpenTelemetry Collector in front and set `compression: none` on its otlphttp exporter.

   ```sh
   OTEL_EXPORTER_OTLP_ENDPOINT=https://sensorium.example.com
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
   OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<ingest token>
   ```

3. Connect an agent to the MCP endpoint.

   ```sh
   claude mcp add --transport http sensorium https://sensorium.example.com/mcp \
     --header "Authorization: Bearer <SENSORIUM_MCP_TOKEN>"
   ```

4. Ask it what broke. `error_summary` and `top_sources` are the usual first calls.

## Configure

Every setting is an environment variable in `.env`. `POSTGRES_PASSWORD` and `SENSORIUM_MCP_TOKEN` are required, and the `SENSORIUM_RETENTION_*_DAYS` keys set how long data stays. [.env.example](https://github.com/zyx1121/sensorium/blob/main/.env.example) documents every key.

Part of [zyx.tw](https://www.zyx.tw): [Privacy](https://www.zyx.tw/privacy), [Terms](https://www.zyx.tw/terms).