/investigating-logs

name: investigating-logs
description: >
  Investigate logs in a PostHog project: verify a service or deployment is healthy, explain an error spike,
  triage an incident, or understand what a log stream is saying. Use when the user asks to "check the logs",
  asks whether a service, deploy, release, or change is working or broke anything, asks why errors are up or
  what changed, wants the logs of one trace or run, or wants a daily service health report. Routes the logs
  MCP tools (service health, group-by, before/after pattern diffing, context around a trace or run, bucketed
  counts, raw rows) so investigations start from summaries instead of raw rows or hand-written SQL over the
  logs table.

Investigating logs

Investigation is a narrowing problem: **summarize before you read**. One `posthog:logs-patterns` call compresses millions of lines into at most 200 templates, and one `posthog:logs-patterns-diff` call answers "what is different about now vs. before" directly. Raw rows (`posthog:query-logs`) are the last step of an investigation, never the first.

The entry points, in order:

1. **Health**: `posthog:apm-service-health` (tracing) or `posthog:logs-services-create` — which services are worse, silent, or new. 2. **Shape**: `posthog:logs-group-by` (counts by service, severity, pattern, or attribute) or `posthog:logs-patterns-diff` (which messages are new or worse). 3. **Context**: `posthog:logs-context` — the timeline around one log line, trace, or run, with its correlation keys.

Follow the `next` field of each response. It holds a prefilled follow-up call.

When to use this skill

• "Check the logs" / "is service X healthy?" / "did my deploy (or model bump, config change, migration) break anything?"
• "Why are errors up?" / "explain this spike" / incident triage — "what changed?"
• "What is this service logging?" — orienting in an unfamiliar or noisy stream.
• Finding the log evidence for a failure reported elsewhere (an alert, an error-tracking issue, a user complaint).

When _not_ to use this skill

• Creating or tuning log alerts — that's `authoring-log-alerts`.
• Analytics over product events, persons, or insights — that's `querying-posthog-data`.
• HogQL exposes a `logs` table via `posthog:execute-sql`, but do not investigate through it:

hand-written SQL over logs routinely hits read-byte caps and re-derives what the tools below do in one cheap call. Reserve SQL for the rare case of joining log-derived facts with non-log data.

Tools

| Tool | Job | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `posthog:logs-services-create` | Top-25 services with log_count, error_count, error_rate, sparkline. Orientation. | | `posthog:logs-patterns` | Mine one window's message templates, ordered by frequency. "What is this stream saying?" | | `posthog:logs-patterns-diff` | Diff templates between two windows: new / rate-shifted / gone, with first-seen. "What changed?" | | `posthog:logs-group-by` | Counts grouped by up to 3 dimensions (service, severity, pattern, attribute). | | `posthog:logs-context` | Logs around one log line, trace, or attribute value (a run), plus correlation keys and spans. | | `posthog:logs-count` / `posthog:logs-count-ranges` | Scalar and time-bucketed counts for a filter. Localize volume before pulling rows. | | `posthog:logs-sparkline-query` | Volume over time broken down by severity or service (the one bucketed view with a breakdown). | | `posthog:logs-facet-values-create` | Distribution of severity/service (or a resource attribute) under a filter. | | `posthog:logs-attributes-list` / `posthog:logs-attribute-values-list` | Discover attribute keys and values before building filters. | | `posthog:query-logs` | Raw rows. Endpoint of every drill-down, entry point of none. |

Each tool's own description documents its parameters and response shape — read it before calling.

Pick the workflow by question shape

"Is it healthy?" — post-deploy / post-change verification

The user changed something (deploy, model bump, config, migration) and wants to know the logs still look right.

1. Pin down the change time and the affected service(s). Ask if the user hasn't said; the diff is meaningless without a boundary. 2. Orient with `posthog:logs-services-create`: is the service still logging at all, and what is its error_rate now? A service that went silent fails verification just as hard as one that started erroring. 3. `posthog:logs-patterns-diff` with `query.dateRange` from the change time to now and `baselineDateRange` set to a comparable window just before the change, scoped to `serviceNames`. New error/fatal templates right after a change are the classic regression signature; large `rate_ratio` shifts on existing error templates are the second thing to check. 4. Check volume continuity with `posthog:logs-count-ranges` spanning before and after the boundary: a rate discontinuity (crash loop, restart storm, silence) shows up here even when message content looks unchanged. 5. Drill only the suspects: pivot each suspicious pattern to raw lines via its `match_regex` with `posthog:query-logs`.

A pass verdict needs all three: no new error templates, no large