Superlog: an open-core OpenTelemetry workspace with a pluggable agent runner
Open-source observability tool that uses AI agents to self-heal your software
At a glance
- What is it?
- Superlog ingests OTLP traces, logs and metrics, groups them into incidents, and exposes an agent runner interface for investigation runtimes. The community edition is Apache-2.0; the agent that actually reasons about your incidents is a separate concern.
- Who is it for?
- Adopt the community edition if you already emit OTLP and want incident grouping plus a local debugging surface you can run with docker compose up -d, and if you are willing to write your own investigation runtime against the agent runner interface. Do not adopt it expecting an out-of-the-box self-healing agent: the default community runner only records a local incident summary.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Superlog targets: signal volume, not signal absence
Most teams already emit telemetry. The README frames the problem as noise rather than blindness: Superlog ingests traces, logs and metrics, then groups noisy signals into incidents. That is a different product category from a collector or a dashboard. The unit of work is the incident, not the span.
The intended user is an engineer debugging a production system who is tired of correlating three panes by hand. The repository describes a local-first product surface, which means the debugging session happens against software you run, not against someone else's tenant. The topics list includes self-hosted, so that framing is deliberate rather than incidental.
The company behind it is in Y Combinator P26 and ships a hosted Cloud edition with a free tier, a pay-to-go plan and monthly credit packs. That commercial context matters for anyone evaluating the community edition, because it tells you where the boundary between free and paid is likely to sit.
What the community edition actually contains
The README is unusually explicit about scope. This repository holds the fully open-source, free community edition, and it enumerates the parts: web app and API, OTLP ingest proxy, worker processes for incident grouping and background jobs, Postgres schema and ClickHouse-backed telemetry queries, agent runner interfaces for pluggable investigation runtimes, and a default community agent runner that records a local incident summary.
That last item is the one to read twice. The agent runner interface is the extensibility point. The default implementation does not investigate anything; it records a summary locally. The description on the repository page says the tool uses AI agents to self-heal your software, and the code layout does include apps/worker for agent orchestration, but the shipped community runner is a stub relative to that description. Anyone arriving because of the self-healing phrasing should treat the agent as something they build, not something they download.
The storage layer is split. Postgres holds the schema, and telemetry queries go through ClickHouse. Two datastores is a real operational cost, and the README does not explain the retention or partitioning policy behind that choice.
Data flow: OTLP in, incidents out
The architecture visible in the repository layout is a four-process pipeline. apps/proxy is the OTLP intake proxy, listening on port 4101 in the default local setup. It is the only component your instrumented services need to know about. apps/api is the HTTP API on port 4100, and apps/web is a Vite and React frontend on port 5173.
Between ingest and query sits apps/worker, described as background workers and agent orchestration. That is where grouping happens. The packages/fingerprint directory holds telemetry fingerprinting helpers, which is the mechanism that makes grouping possible at all: signals have to be reduced to a stable identity before they can be collapsed into one incident. The README does not document the fingerprinting algorithm, so the grouping quality is something you would have to read out of that package rather than from the docs.
packages/db holds the Drizzle schema and migrations. Drizzle is the schema layer, which means migrations are code, and the db:migrate script is the intended path for applying them. The default community agent runner sits at the end of that flow and writes a local incident summary instead of dispatching an investigation.
Getting the local stack running
The README states three prerequisites: Node.js 20 or newer, pnpm 9 or newer, and Docker. Installation is four commands. First, pnpm install. Then docker compose up -d to start the local stack. Then pnpm --filter @superlog/db db:migrate to apply the Drizzle migrations. Then pnpm dev.
The filter flag matters. It scopes the migration to the @superlog/db package rather than running a root-level script, which suggests the workspace is a pnpm monorepo with per-package scripts. If you skip that step, the API and worker will start against an unmigrated Postgres instance.
Default ports are worth noting because they are fixed in the README: web on 5173, API on 4100, OTLP intake on 4101. The intake port is the one you point your OpenTelemetry exporter at. Typechecking is a separate command, pnpm typecheck, and there is no test command documented in the material provided.
The README also offers an agent-driven install path: run npx skills add superloglabs/skills --all and use the skills to install Superlog in this project. That routes installation through a coding agent rather than a human reading the quick start. It is a legitimate convenience, but it also means the agent decides which files to touch, so review the diff.
The open-core boundary and what it costs you
Superlog is open-core, and the README says so directly. The community edition is Apache-2.0. The hosted Cloud edition has a free tier, a pay-to-go plan and monthly credit packs. The repository does not state which features are exclusive to Cloud beyond the existence of the paid tiers, so the long-term feature split is not something you can read off this material.
Apache-2.0 is permissive. It includes an express patent grant and does not impose copyleft on your own code, which is the usual reason teams pick it over AGPL for infrastructure they embed. This is not legal advice, and the licence text in LICENSE.md is the authority, not this paragraph. If you plan to redistribute a modified Superlog, read the NOTICE and attribution requirements yourself.
Maintenance cost is the harder question. Four applications plus two datastores plus a migration pipeline is not a small footprint. There are no releases retrieved for this repository, so there is no versioned upgrade path documented in the supplied material. Upgrades would mean tracking main and re-running pnpm --filter @superlog/db db:migrate against your own Postgres. Whether migrations are additive or destructive is not stated, and that is the first thing to check before running them against data you care about.
Where the agent story is thinner than the tagline
The repository description promises AI agents that self-heal your software. The README promises agent runner interfaces for pluggable investigation runtimes, plus a default community runner that records a local incident summary. Those are not the same claim, and the gap between them is the honest limitation of this project as shipped.
A pluggable interface is a reasonable design. It keeps the investigation runtime out of the ingest path and lets you swap in whatever model or workflow you trust. But it pushes the hard part onto you: defining what an investigation is, what context it receives, and what it is allowed to change. Nothing in the supplied material describes a remediation action, a write-back path, or a safety boundary around automated changes. Self-healing, in the sense of the tool modifying your production system, is not evidenced here.
There is a second limitation in the storage design. ClickHouse-backed telemetry queries alongside a Postgres schema means you operate two databases with different backup, scaling and failure characteristics. For a small team, that is the cost that decides the adoption question more than any feature list.
How this differs from Grafana and the LGTM stack
The obvious alternative for someone already on OpenTelemetry is the Grafana stack: an OTLP endpoint, Loki for logs, Tempo for traces, Mimir or Prometheus for metrics, and Grafana in front. It also ingests OTLP and it also self-hosts.
The difference is where the work happens. Grafana gives you query surfaces and alert rules; you write the rules, and correlation across signals is something you construct with queries and dashboards. Superlog puts a worker between ingest and storage whose job is to group signals into incidents before a human looks at them, with packages/fingerprint supplying the identity function that grouping depends on. That is a pre-aggregation approach rather than a query-time approach.
The trade-off is control. With Grafana you can always ask an arbitrary question of raw data because the raw data is the primary artifact. With incident grouping, the grouping decision is made upstream, and if the fingerprint collapses two things that should stay separate, you are debugging the grouper. The README does not document a way to inspect or override fingerprint decisions, which is a gap worth confirming before you commit to the model.
A second alternative is doing nothing new: keep your current collector and add a deduplication or alert-grouping layer in front of your existing paging system. That is cheaper if your actual pain is alert fatigue rather than debugging.
Who should adopt it, and what to verify first
Adopt the community edition if you already emit OTLP, you want a self-hosted debugging surface, and you are prepared to write an investigation runtime against the agent runner interface. The local stack is four commands and three ports, which is a low enough barrier to evaluate in an afternoon. The Apache-2.0 licence removes the usual redistribution worry for internal infrastructure.
Do not adopt it if the self-healing claim is what drew you in. The default community runner records a local incident summary. That is the shipped behaviour. If you need automated remediation today, this is not that, and the README does not claim otherwise.
Do not adopt it either if operating ClickHouse alongside Postgres is more infrastructure than your team wants to own, or if you need a versioned release channel. No releases were retrieved for this repository, so there is no tagged upgrade path in the supplied material.
Three things to verify before you point production telemetry at it. Read packages/fingerprint and confirm the grouping identity matches how your services actually fail; a fingerprint keyed on the wrong attributes will merge unrelated incidents. Read the Drizzle migrations in packages/db and check whether they are additive, since pnpm --filter @superlog/db db:migrate is the only upgrade mechanism documented. And read the agent runner interface in apps/worker to see what context a custom runtime receives, because that interface is the actual product boundary here, not the web UI.
Editorial conclusion
Adopt the community edition if you already emit OTLP and want incident grouping plus a local debugging surface you can run with docker compose up -d, and if you are willing to write your own investigation runtime against the agent runner interface. Do not adopt it expecting an out-of-the-box self-healing agent: the default community runner only records a local incident summary. Before committing, verify two things in the repository itself: whether packages/fingerprint defines the grouping logic you want, and whether the Postgres plus ClickHouse split fits your existing storage budget.
Community notes