Log Analysis

Log Analysis

When to use this skill

• The main job is read-only log triage, not code changes or monitoring design.
• The user wants the first actionable blocker, not a paraphrase of every line.
• The evidence is application, API, worker, proxy, container, pod, browser, CI, or JSON logs.
• The user needs the repeated signature or blast radius summarized after the first failure is isolated.
• The prompt is really "which lines matter / what is the real error / where does the cascade start?" even if the user never says "triage".

Do not use this skill as the main workflow when:

• The logs are Unity / Unreal build, cook, package, editor, or player logs → use game-build-log-triage.
• The real job is instrumentation, dashboards, alerting, ingestion, retention, or observability coverage → use monitoring-observability.
• The likely blocker is already known and the user now needs reproduction, hypotheses, or fixes → use debugging.
• The main job is repeated anomaly/rule hunting across logs or telemetry families rather than first-failure triage → use pattern-detection.

Core idea

log-analysis should act like a packet router, not a giant troubleshooting encyclopedia.

1. Normalize the request into one primary log packet. 2. Narrow the evidence slice before interpreting it. 3. Isolate the earliest actionable failure. 4. Group repeated fallout into a pattern / blast radius note. 5. Route out as soon as the work becomes debugging, observability design, anomaly hunting, or engine-specialist triage.

Read these support docs before choosing the packet:

• references/intake-packets-and-route-outs.md
• references/triage-playbook.md
• references/source-boundaries.md

Instructions

Step 1: Normalize the request

Convert the prompt into this intake shape first:

log_analysis_packet:
  primary_packet: app-runtime | container-runtime | browser-plus-api | ci-cascade | structured-json | security-signal
  source_shape: app | proxy | worker | browser | ci | container | pod | json | mixed | unknown
  environment: local | ci | staging | production | browser | container | pod | unknown
  failure_goal: first-blocker | cascade-start | repeated-signature | blast-radius | suspicious-access | unknown
  anchor: timestamp | request-id | trace-id | job-build-id | browser-route | none | unknown
  route_after: stay-here | debugging | monitoring-observability | pattern-detection | game-build-log-triage

Choose one primary packet for the run. If two seem plausible, pick the cheaper packet that reduces uncertainty fastest.

Step 2: Choose the packet

Packet rules:

• Prefer app-runtime for plain text stack traces and server logs.
• Prefer container-runtime when restart timing, pod identity, or env/deploy context matters.
• Prefer browser-plus-api when frontend symptoms are not sufficient on their own.
• Prefer ci-cascade when the visible failure may be generic abort noise.
• Prefer structured-json when fields make grouping and correlation cheaper than free-text scanning.
• Prefer security-signal only when suspicious access/auth behavior is the main job; otherwise keep security-looking noise inside the packet that owns the first blocker.

Step 3: Narrow the slice before reading everything

Apply at least one narrowing move before interpreting the logs:

• limit by time window
• limit by request / trace / job / build / session / tenant identifier
• separate fatal/actionable lines from retries and fallout
• separate one noisy source from many affected sources
• separate browser symptom lines from server-side blocker lines
• in CI, locate the earliest failing step before summarizing the full transcript

Useful heuristics by packet:

• app-runtime → exception / fatal / failed / timeout / refusal first
• container-runtime → restart window + dependency/connectivity/env mismatch first
• browser-plus-api → backend auth/config/runtime evidence before generic client symptoms
• ci-cascade → earliest import/config/build/test failure before abort/footer lines
• structured-json → group by message family, exception class, request ID, or service before reading raw rows
• security-signal → distinguish broad probing from one broken client before escalating

Step 4: Isolate the first actionable failure

Use this order: 1. Hard stop — crash, panic, uncaught exception, process exit, build failure 2. Dependency / environment blocker — missing config, secret, DNS, file, service, auth, or connection 3. Request / runtime failure — 500, timeout, rejected promise, queue poison message, parser failure 4. Fallout — retries, secondary warnings, repeated health-check failures, broad abort text

Do not report 20 repeated downstream lines as 20 different causes.

Step 5: Correlate and classify

If the evidence spans more than one source, correlate instead of concatenating.

Primary classification buckets:

• missing-config-or-secret
• dependency-or-connection
• auth-or-permission
• request-or-runtime-error
• data-shape-or-validation
• resource-or-capacity
• browser-network-mismatch
• ci-build-test-failure
• security-or-suspicious-pattern
• unknown-needs-more-context

Correlation anchors to prefer:

• timestamp window
• request / trace / correlation ID
• job/build ID or CI step
• service / worker / pod / container name
• route, browser action, or API endpoint
• user / tenant / session identifier when safe to mention

Step 6: Return a triage brief

Default response shape:

# Log Triage

## Source
- Packet: app-runtime | container-runtime | browser-plus-api | ci-cascade | structured-json | security-signal
- Environment: local | CI | staging | production | browser | container | pod
- Confidence: high | medium | low

## First actionable failure
- Line or excerpt: `...`
- Why it matters: ...
- Why later lines look secondary: ...

## Pattern / blast radius
- Repeated signature: ...
- Scope: one request | repeated requests | one worker | one deploy window | one environment | broad

## Classification
- Primary bucket: ...
- Secondary bucket: ...

## Likely root cause
- 1-3 sentence explanation grounded in the evidence

## Next read-only checks
1. ...
2. ...
3. ...

## Route-out
- stay in `log-analysis` | `debugging` | `monitoring-observability` | `pattern-detection` | `game-build-log-triage`

Step 7: Route out aggressively

Switch when the next job is no longer first-failure log triage:

• Reproduction, hypotheses, code/config fixes → debugging
• Dashboards, alerts, ingestion, telemetry coverage, retention → monitoring-observability
• Repeated signature hunting across many windows or datasets → pattern-detection
• Unity / Unreal build/editor/package logs → game-build-log-triage

If the excerpt is too short or starts mid-cascade: 1. mark confidence low 2. ask for the earliest error cluster or 20-80 lines around the first blocker 3. ask for one anchor only if needed: time window, request ID, job/build, pod/container, or browser route 4. do not pretend certainty from a truncated excerpt

Examples

Example 1: Container dependency failure

Prompt:

kubectl logs shows Error: connect ECONNREFUSED redis:6379 and then dozens of job retry failed lines.

Good response shape:

• choose container-runtime
• identify the Redis connection failure as the first actionable blocker
• group later retry lines as fallout
• route next to debugging or monitoring-observability only after the blocker is isolated

Example 2: Browser + API mismatch

Prompt:

Browser console says Failed to fetch, the network tab shows 401 on /api/session, and the server log says JWT audience invalid.

Good response shape:

• choose browser-plus-api
• identify backend auth validation as the actionable blocker
• treat browser failure as a symptom, not the cause
• route next to debugging once the config/code suspect is clear

Example 3: CI cascade

Prompt:

CI ends with test suite aborted, but earlier there is ModuleNotFoundError: No module named 'dotenv'.

Good response shape:

• choose ci-cascade
• isolate the earliest import failure
• treat the abort/footer text as fallout
• route next to debugging after the failing dependency path is known

Example 4: Automation/webhook JSON logs

Prompt:

These JSON webhook logs show repeated status=429 retries after one invalid API key response. What actually matters?

Good response shape:

• choose structured-json or security-signal depending on whether auth abuse or one bad credential is the primary job
• isolate the first credential/auth failure
• summarize retry volume separately
• route repeated pattern hunting to pattern-detection only if the user wants broader anomaly work

Best practices

1. Choose the smallest packet that can answer the question. 2. Lead with the earliest blocker, not the loudest line. 3. Group repeated fallout into one signature or blast-radius summary. 4. Correlate browser/network/app evidence instead of summarizing each source independently. 5. Keep all suggested checks read-only inside this skill. 6. Treat engine-specific logs as a hard specialist boundary. 7. Route out as soon as the work becomes debugging, observability design, or anomaly hunting.

References

• references/intake-packets-and-route-outs.md
• references/triage-playbook.md
• references/source-boundaries.md

Intake packets and route-outs

Packet chooser

Use one primary packet per run.

Fast anchor ladder

Pick the cheapest anchor that reduces uncertainty fastest: 1. timestamp window 2. request / trace / correlation ID 3. job/build/stage ID 4. service / worker / pod / container name 5. route or browser action 6. user / tenant / session identifier (only when safe to mention)

Packet heuristics

• app-runtime → look for the first exception or hard stop before retry noise.
• container-runtime → compare restart timing, service reachability, and env/config assumptions first.
• browser-plus-api → treat browser errors as symptoms until backend evidence confirms the blocker.
• ci-cascade → generic abort/footer lines are almost never the real root cause.
• structured-json → group by message family / exception class before reading row by row.
• security-signal → separate broad probing from one broken client or stale credential before escalating.

Quick route-outs

• First blocker isolated and user wants reproduction/fix hypotheses → debugging
• User really needs dashboards, alerts, ingestion, retention, or coverage design → monitoring-observability
• User wants repeated anomaly/rule hunting across wider log or telemetry windows → pattern-detection
• Logs are Unity / Unreal build, editor, package, or player specific → game-build-log-triage

Smell test

If your next paragraph is mostly about code fixes, monitor design, or broad anomaly programs instead of the first actionable blocker plus blast radius, log-analysis has already done its job.

Source Boundaries for log-analysis

log-analysis owns

• Read-only triage of raw logs or excerpts
• Identifying the first actionable failure
• Grouping repeated signatures
• Correlating browser/network/app or container/CI evidence
• Recommending next read-only checks

Route to debugging

Use debugging when the likely cause is already narrowed to code behavior and the next job is reproduction, fix design, or verification.

Examples:

• A specific function or module is now the suspect
• The main question is how to reproduce or fix the bug
• The user needs regression tests or code-level debugging steps

Route to monitoring-observability

Use monitoring-observability when the request is about instrumentation, log collection, dashboards, retention, alerting, or platform setup.

Examples:

• Add structured logging or correlation IDs
• Set up Prometheus/Grafana/ELK/Datadog
• Design alert rules or ingestion pipelines
• Improve retention/indexing/queryability

Route to pattern-detection

Use pattern-detection when the main job is repeated anomaly or rule hunting across many log windows, event families, or telemetry records rather than isolating one first actionable blocker.

Examples:

• Compare repeated error signatures across many releases or cohorts
• Hunt for suspicious retry or abuse patterns over time
• Build a reusable rule pack for recurring event shapes
• Separate broad anomaly detection from one concrete incident

Route to game-build-log-triage

Use game-build-log-triage for Unity or Unreal engine-specific editor, package, player, cook, compile, shader, or asset pipeline logs.

Examples:

• Editor.log
• BuildCookRun
• UHT / UBT
• Unity package/import/asmdef failures
• Unreal plugin/module/cook failures

Practical rule

If the user mainly needs to know which lines matter, stay in log-analysis. If the user mainly needs to know how to fix code, move to debugging. If the user mainly needs to know how to build the logging/monitoring system, move to monitoring-observability. If the user mainly needs engine-specific build/editor/runtime log triage, move to game-build-log-triage.

Log Triage Playbook

Use this checklist before writing conclusions:

1. Name the source first

• application/runtime log
• access/proxy log
• JSON/structured log
• browser console
• browser network
• CI transcript
• container/pod output
• mixed

2. Find the first actionable failure

• fatal line
• dependency/config/auth blocker
• request/runtime failure
• later fallout/noise

3. Anchor the investigation

• timestamp window
• request/trace/build ID
• service/container/pod name
• user/session/tenant identifier (masked)

4. Describe blast radius

• one request
• repeated requests
• one worker/job
• one deploy window
• one environment
• broad/systemic

5. Return a short triage brief

• source
• first actionable failure
• pattern/blast radius
• likely root cause
• next read-only checks
• handoff target

Red flags

• The excerpt starts after the true cause.
• The only visible evidence is a generic abort or timeout.
• Secrets or user data appear in the pasted logs.
• The request is actually asking for observability pipeline setup rather than log triage.
• The logs are Unity/Unreal engine-specific and should route to game-build-log-triage.