introduction

you keep two systems in sync today: the code that ships and the dashboards that prove it works. horion sits between them. it reads your repo, cross-references live telemetry from datadog, grafana, prometheus, or any OTel collector, and tells you exactly which spans, counters, and structured logs are missing — then opens a PR with the fix.

how horion works#

every analysis is the same five-stage flow — repo on the left, results on the right, knowledge base feeding the engine from below. hover any zone in the diagram to trace the connectors.

1. connect

   authorize the horion app on github, gitlab, or bitbucket. horion requests the minimum scopes needed: read source, open pull requests, read CI status. you can revoke at any time.

2. walk

   the horion agent walks the source tree, classifies files (handlers, jobs, bootstrap, config), and locates instrumentation: tracer.startSpan, logger.info, prometheus counters, datadog wrappers, OTel SDK imports — across python, go, typescript, java, ruby, and rust.

3. cross-reference

   if you connected a telemetry backend, horion correlates code findings with what is actually being emitted. a span declared in code but never seen in datadog becomes a higher-confidence finding than a span that simply has low cardinality.

4. score

   the scoring engine resolves each pillar independently and combines them into a weighted global score (see pillars & weights below).

5. fix

   for findings horion is confident about, it opens a real PR with the proposed diff and rationale. push back in a PR comment and horion refines the patch on the same branch — no need to close the PR.

the four pillars & how they're weighted#

the global score is a weighted average of five sub-scores. observability (metrics, logs, traces) accounts for 80 % — it's the product's core. security and cost are cross-cutting modifiers that pull the score down when gaps are present, but never dominate it.

instrumentation gate

before scoring metrics or traces, horion checks whether the repo is instrumented at all. it looks for SDK imports (opentelemetry, ddtrace, prometheus_client, statsd, etc.) and infra-level agents (datadog agent, OTel collector in compose / k8s manifests). if neither is present, the affected pillars are zeroed and the finding is upgraded to critical — perfect score requires actual emission, not declarations.

scoring & grades#

each pillar resolves independently to 0–100. findings deduct points by severity:

• critical — −20 (dimension) / −25 (pillar)
• warning — −10 (dimension) / −12 (pillar)
• info — −3 (dimension) / −5 (pillar)

the global score is the weighted average of the five pillars. the grade letter maps directly from the score band:

findings & severity

every finding has a severity, a pillar, a source location, and (when possible) a proposed patch. the dashboard ranks findings by impact — a missing span on a high-traffic egress hits harder than the same span on a cold path.

integrations · SCM#

horion connects to the three SCMs you already use. analysis triggers on push and pull request events; fix PRs are opened back into the same provider.

integrations · telemetry#

horion works without a telemetry backend — it analyzes your instrumentation source. connecting one sharpens cost-impact estimates and ranks findings by what is actually being emitted in production.

datadog

read-only API key. horion queries metrics, logs, and APM endpoints to confirm spans declared in code are landing, and to detect high-cardinality tags driving your bill.

grafana & prometheus

point horion at your prometheus endpoint (or grafana data source proxy). horion uses recording rule names + scrape configs to map metric definitions back to the services that emit them.

opentelemetry

the OTel collector is the most flexible option — horion ingests OTLP directly and correlates spans, metrics, and logs across the same trace_id. recommended when you run a polyglot stack.

backend architecture#

horion runs three durable services behind the scoring engine. nothing is self-hosted — the knowledge base ships fully managed.

• horion agent — the langgraph-driven analysis engine. each node walks one slice of the repo (handlers, configs, dependencies, instrumentation) and writes to a typed AgentState. nodes never return {}; every pass updates at least one declared key, even on skip paths.
• horion worker — celery + redis pipeline that chunks, embeds, and syncs the knowledge base on schedule or on demand. it reads source blobs and exports from amazon S3 and writes vectors to the index.
• knowledge base — vector database used for semantic search and RAG-style retrieval during analysis. the agent queries it for similar prior findings, proven fix patterns, and per-org code conventions.

streaming results

the dashboard receives pillar scores as they resolve via SSE. analyses typically complete in 30–120 s end-to-end, with each pillar streaming an update the moment it's ready.

MCP server#

the horion MCP server exposes the same context the dashboard sees as tool-callable endpoints. plug it into cursor, claude code, or devin and your coding agent can query analyses, drill into findings, and drive fixes without leaving the editor.

{
  "mcpServers": {
    "horion": {
      "command": "npx",
      "args": ["-y", "@horion/mcp-server"],
      "env": { "HORION_TOKEN": "hz_live_••••••" }
    }
  }
}

tools the MCP server exposes:

• analyses.list — recent analyses across the workspace
• analyses.get — pillar scores, findings, fix PR status
• findings.search — full-text + semantic search across findings
• findings.explain — model rationale + source location
• repo.score_history — score timeline for a repo (90 days)

quickstart#

once a repo is connected, you can trigger an analysis from the dashboard, the cli, or the api. all three return the same result — pick the one that fits your workflow.

# install once, scoped to the active org
$ npm install -g @horion/cli

# authenticate with a personal token from horion.pro/settings/tokens
$ horion auth login --token hz_live_••••••

# run a full analysis on the current repo
$ horion analyze \
    --repo acme/payments \
    --type full \
    --tag team=payments \
    --tag env=prod

next steps#