AutoGineer
Generated banner for Omnibus Instrument Logs
Generated logo for Omnibus Instrument Logs

Omnibus Instrument Logs

PostHogOfficialCreated by PostHog

  • Skill
  • Tool integration
  • Data and AI
  • MIT
  • Low risk
Download ZIP

From the author

Add PostHog log capture to track application logs. Use after implementing features or reviewing PRs to ensure meaningful log events are captured with structured properties. Also handles initial OTLP exporter setup if not yet configured.
— the description by PostHog

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to instrumenting applications for log collection via PostHog. It guides the user through detecting their current logging stack, installing necessary OpenTelemetry SDKs, configuring OTLP exporters, and ensuring logs are enriched with structured properties for better observability. It also supports forwarding existing Datadog logs to PostHog, ensuring that developers can centralize their system logs alongside product analytics and session replays.

What it does

  • Detects the application's language, framework, and existing logging infrastructure.
  • Configures OpenTelemetry OTLP exporters to send logs to PostHog.
  • Integrates log capture alongside existing logging handlers without replacing them.
  • Promotes the use of structured, key-value based logging for better searchability.
  • Sets up environment variables for secure API key and endpoint management.
  • Provides a path to forward existing Datadog log streams to PostHog.

When to use it

  • When you need to start capturing application logs in PostHog for the first time.
  • After implementing new features or reviewing pull requests to ensure relevant events are logged.
  • When you want to transition from plain text logging to structured, queryable logs.
  • When you need to integrate PostHog logging into an existing Datadog-based setup.

Advantages

  • Centralizes system logs with product analytics and session replays.
  • Uses industry-standard OpenTelemetry protocols for broad compatibility.
  • Maintains existing logging architecture by adding exporters as a sidecar or secondary output.
  • Encourages best practices like wide-event logging for easier debugging.

Usage examples

“Set up PostHog log capture for my Node.js application.”
The agent will analyze the project, install the required OpenTelemetry packages, configure the OTLP exporter, and guide you through setting the necessary environment variables.
“I am already using Datadog for logs, how do I send them to PostHog?”
The agent will provide instructions to update your Datadog agent configuration to point to the PostHog Datadog-compatible ingest endpoint.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/posthog/omnibus-instrument-logs/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip omnibus-instrument-logs.zip -d .agents/skills

Documentation by PostHog

Add PostHog log capture

Use this skill to add PostHog log capture for new or changed code. Use it after implementing features or reviewing PRs to ensure meaningful log events are captured with structured properties. If PostHog log export is not yet configured, this skill also covers initial OTLP exporter setup. Supports any platform or language.

Supported platforms: Next.js, Node.js, Python, Go, Java, Datadog, and any language via OpenTelemetry.

Instructions

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

  • Detect the language, framework, and existing logging setup.

  • Look for log libraries (winston, pino, logging module, logrus, log4j, serilog, etc.).

  • Look for lockfiles to determine the package manager.

  • Check for existing PostHog log export setup. If the OTLP exporter is already configured, skip to STEP 5 to add log capture for new code.

STEP 2: Research log capture. (Skip if PostHog log export is already configured.) 2.1. Find the reference file below that matches the detected platform — it is the source of truth for OTLP exporter configuration and integration with existing logging. Read it now. 2.2. If no reference matches, use the "Other Languages" reference as a fallback — it covers the generic OpenTelemetry approach.

STEP 3: Install dependencies. (Skip if PostHog log export is already configured.)

  • Install the OpenTelemetry SDK and OTLP exporter packages for the detected platform.

  • Do not manually edit dependency files — use the package manager's install command.

  • Always install packages as a background task. Don't await completion; proceed with other work immediately.

STEP 4: Configure the OTLP exporter. (Skip if PostHog log export is already configured.)

  • PostHog logs use the OpenTelemetry protocol. Set up an OTLP exporter pointed at PostHog's ingest endpoint.

  • Follow the platform-specific reference for the exact configuration.

STEP 5: Integrate with existing logging.

  • Add the PostHog log exporter alongside existing logging. Don't replace existing log handlers or outputs.

  • Do not alter the fundamental architecture of existing files. Make additions minimal and targeted.

  • You must read a file immediately before attempting to write it.

STEP 6: Add structured properties.

  • Ensure logs include structured key-value properties for filtering and search in PostHog.

  • Prefer structured log formats with key-value properties over plain text messages.

STEP 7: Set up environment variables.

  • If an env-file-tools MCP server is connected, use check_env_keys then set_env_values to configure the PostHog API key, host, and OpenTelemetry endpoint.

  • Reference these environment variables in code instead of hardcoding them.

Reference files

  • references/nextjs.md - Next.js logs installation - docs

  • references/nodejs.md - Node.js logs installation - docs

  • references/python.md - Python logs installation - docs

  • references/go.md - Go logs installation - docs

  • references/java.md - Java logs installation - docs

  • references/datadog.md - Datadog logs installation - docs

  • references/other.md - Other languages logs installation - docs

  • references/start-here.md - Getting started with logs - docs

  • references/search.md - Search logs - docs

  • references/best-practices.md - Logging best practices - docs

  • references/troubleshooting.md - Logs troubleshooting - docs

  • references/link-session-replay.md - Link session replay - docs

  • references/debug-logs-mcp.md - Debug logs with mcp - docs

Each platform reference contains specific OTLP configuration, SDK setup, and integration patterns. Find the one matching the user's stack.

Key principles

  • Environment variables: Always use environment variables for PostHog keys and OpenTelemetry endpoints. Never hardcode them.

  • Minimal changes: Add log export alongside existing logging. Don't replace or restructure existing logging code.

  • OpenTelemetry: PostHog logs use the OpenTelemetry protocol. Configure an OTLP exporter pointed at PostHog's ingest endpoint.

  • Structured logging: Prefer structured log formats with key-value properties over plain text messages.

Files

references/java.md

Java logs installation - Docs

  1. 1

    Install OpenTelemetry packages

    Required

    Add the following dependencies to your pom.xml:

    XML

    PostHog AI

    <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>1.32.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
    <version>1.32.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
    <version>1.32.0</version>
</dependency>

  2. 2

    Get your project token

    Required

    You'll need your PostHog project token to authenticate log requests. This is the same key you use for capturing events and exceptions with the PostHog SDK.

    Important: Use your project token which starts with phc_. Do not use a personal API key (which starts with phx_).

    You can find your project token in Project Settings.

  3. 3

    Configure the SDK

    Required

    Set up the OpenTelemetry SDK to send logs to PostHog.

    Java

    PostHog AI

    import io.opentelemetry.api.logs.GlobalLoggerProvider;
import io.opentelemetry.sdk.logs.SdkLoggerProvider;
import io.opentelemetry.sdk.logs.export.BatchLogRecordProcessor;
import io.opentelemetry.exporter.otlp.logs.OtlpHttpLogRecordExporter;
SdkLoggerProvider loggerProvider = SdkLoggerProvider.builder()
    .addLogRecordProcessor(
        BatchLogRecordProcessor.builder(
            OtlpHttpLogRecordExporter.builder()
                .setEndpoint("https://us.i.posthog.com/i/v1/logs")
                .addHeader("Authorization", "Bearer <ph_project_token>")
                .build()
        ).build()
    )
    .build();
GlobalLoggerProvider.set(loggerProvider);

    Alternatively, you can pass the API key as a query parameter:

    Java

    PostHog AI

    OtlpHttpLogRecordExporter.builder()
    .setEndpoint("https://us.i.posthog.com/i/v1/logs?token=<ph_project_token>")
    .build()

  4. 4

    Use OpenTelemetry logging

    Required

    Now you can start logging with OpenTelemetry:

    Java

    PostHog AI

    import io.opentelemetry.api.logs.Logger;
Logger logger = GlobalLoggerProvider.get().get("my-app");
logger.logRecordBuilder()
    .setBody("User action")
    .setAttributes(Attributes.of(
        AttributeKey.stringKey("userId"), "123",
        AttributeKey.stringKey("action"), "login"
    ))
    .emit();

  5. 5

    Test your setup

    Recommended

    Once everything is configured, test that logs are flowing into PostHog:

    1. Send a test log from your application

    2. Check the PostHog logs interface for your log entries

    3. Verify the logs appear in your project

    View your logs in PostHog

  6. Next steps

    Checkpoint

    What you can do with your logs

    ActionDescription
    Why you need logsWhat logs show you that nothing else does
    Search logsUse the search interface to find specific log entries
    Filter by levelFilter by INFO, WARN, ERROR, etc.
    Link session replayConnect logs to users and session replays by passing posthogDistinctId and sessionId
    Logging best practicesLearn what to log, how to structure logs, and patterns that make logs useful in production

    Troubleshoot common issues

Community questions

Ask a question

Was this page useful?

HelpfulCould be better

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs an API key, Needs Python

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
PostHog
Publisher
PostHog (Official)
Source
PostHog/skills · skills/posthog/logs/skills/all · commit a5d30e7
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Also distributed in
PostHog/skills

AutoGineer is not affiliated with or endorsed by PostHog.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download omnibus-instrument-logs.zip