feat(logs): add a logs-setup skill that correlates records to people and sessions

[ThaliaBarrera]

Problem

The logs skill group is docs-only. It declares twelve platform variants and points each at the relevant installation doc, but there's no step chain behind it — it's reference material, and nothing in the wizard drives it. Of the 238 cliEntries in a locally built skill-menu.json, none are logs-related.

Installation is the half those docs already cover well. The half they don't is correlation: attaching posthogDistinctId and sessionId to server-emitted records so a log line resolves to a person and opens their session replay. That's the reason to put logs in PostHog rather than in a standalone log vendor, and today it's left to the reader as something to implement by hand.

It's also the genuinely hard part, and a poor fit for a doc. The answer to "where does this codebase already know who this request belongs to" is different every time — an auth middleware here, a session callback there. A human reading docs has to work that out themselves. An agent reading the codebase can work it out and write the wiring.

Changes

Adds context/skills/logs-setup/: a 7-step chain modelled on migrate, with nextjs and python variants.

detect → install → plan → context → attach → verify → report

Same conventions as migrate throughout: numbered references/ with next_step frontmatter, one step in context at a time, state on disk between steps (.posthog-logs-plan.md), [STATUS] lines, [ABORT] cases, per-step pass/warning/error, and a <wizard-report> block. No commit — the operator reviews the diff.

Four decisions worth a reviewer's attention:

Correlation attaches in exactly one place. A logging.Filter on the OTel handler in Python; a logger wrapper in Next.js. The rule the skill enforces is that a codebase with two hundred log statements should come out of the run with two hundred correlated log statements and roughly one new file. Step 5 explicitly tells the agent to stop and move the shared mechanism if it finds itself editing a third call site by hand.

The client half uses tracing_headers. posthog-js already emits X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID from one config option, which is the convention integration-v2/identify and posthog-best-practices already document — the latter says explicitly "do not hand-roll a fetch wrapper for it". The public logs docs demonstrate threading sessionId through a request body instead, which means touching every route and missing anything that doesn't go through the wrapped function. The skill follows the in-repo convention and notes that these headers are client-controlled, so a server-known user id always outranks them.

Correlation degrades in defined tiers. session (both attributes), person (distinct id only), none. The report states which tier was actually reached and what would raise it. A background worker has no session and shouldn't pretend to have one. The failure mode this is written to avoid is wiring that looks correlated but attaches undefined — so Step 5 requires omitting an absent attribute entirely rather than passing an empty value, and requires that attachment never throws.

The step files stay flat. No references/<variant-id>/ subdirectory, because generateSkill() filters to top-level references/*.md when copying into the zip. migrate-statsig.zip currently ships without the references/statsig/ mapping docs its own steps point at. Happy to file that separately if it's news.

The skill also encodes three things the installation docs bury, all of which fail silently:

• the docs hardcode the US ingestion host, so Step 2 resolves the region from the project's existing PostHog host before writing an endpoint
• the export takes the phc_ project token, not a phx_ personal API key
• Next.js middleware.ts runs on the Edge runtime, a different runtime from the one the OTel provider is registered in, so request context established there is invisible to route handlers

CLI surface

Ships as role: skill, reachable as wizard skill logs-setup-<variant>.

The companion wizard PR registers wizard logs as a native flat command, the same split ai-observability uses (cli: role: skill here, nativeCommandFactory there). Per CONTRIBUTING's promotion criteria I'd rather a maintainer decide whether this should also carry role: command; shipping as skill keeps it out of collision with the native registration in the meantime.

Companion PR: PostHog/wizard#1043.

Test plan

• pnpm test — 137 passed
• pnpm build — builds logs-setup-nextjs.zip and logs-setup-python.zip; skill-menu.json goes 238 → 240 cliEntries with both new skills under a logs-setup category
• Verified the built zip is flat and complete: SKILL.md, all 7 steps, COMMANDMENTS.md, and the 8 fetched docs, with all {display_name} / {references} / {commandments} placeholders substituted and the next_step handoff footers wired 1→7
• pnpm security-scan:skills — zero findings in logs-setup-*. The scan reports 108 findings repo-wide; all are pre-existing in other skills and unchanged by this PR
• Served locally via pnpm dev and confirmed the wizard fetches both variants from localhost:8765 with --local-mcp

LLM context

Written with Cursor. The design came out of reading migrate as the structural template and integration-v2/identify + posthog-best-practices for the existing tracing-header convention, which is what redirected the client half away from the approach the public logs docs demonstrate.

Made with Cursor

[gewenyu99]

The skills themselves look great! There are various nits but I'll stay very high level first.

Here's what I challenge you to think about. Logging is often very sensitive, it comes in at many different levels, it's often pushed across different logging providers, and so much of it is often intentionally anonymized to not get slapped with a GDPR lawsuit.

When should you identify logs? Should you decide for the user or suggest to the user? How do you think about compliance?

If there is a good reason not to log and associate with a person, what other reasons make it valuable to capture logs, especially to PostHog? Think about the context and tasks that push you to reach for logs.

I also suggest you think about logging for monorepos. This is something we haven't solved for the main program (though we're in progress there), but for logs this is especially important. Most logging happens at the service level in the backend for good reason. How do you think about this problem?

Some helpful reading material:
https://posthog.com/docs/logs/pii-scrubbing#quest-item-use-for-free

[gewenyu99]

You will have both region and project details from the Wizard to pass into the agent. I would rely on that and wire that information through.

[gewenyu99]

good scoping

[sarahxsanders]

I feel like this is the stronger of the pair of PRs! the correlation tiers are well thought through. a few things:

1. step 6 can't check what it claims which could report a false failure
2. the command here plus wizard logs in the other PR means there's two ways to run the same thing. we have docs on this if you go take a look! they should be easy to search for
3. feel free to open issues for bugs you find!

[sarahxsanders]

this means the wizard program runs with the command wizard skill logs-setup-nextjs when your intention with the wizard PR looks like to have it run with wizard logs

we have some docs on posthog.com about wizard commands that may help here!

[sarahxsanders]

this rocks! you're looking at it from what partial success looks like and thinking about those outcomes