Add PostHog Debugging Example

[neubig]

Description

This PR adds a PostHog debugging example analogous to the existing DataDog debugging example. The example demonstrates how to automatically fetch events from PostHog, create GitHub issues for debugging, and generate prompts for AI agents to investigate issues.

Fixes #1201

What's New

Files Added

• examples/03_github_workflows/05_posthog_debugging/posthog_debugging.py - Main script with PostHog API integration
• examples/03_github_workflows/05_posthog_debugging/debug_prompt.jinja - Template for agent debugging instructions
• examples/03_github_workflows/05_posthog_debugging/README.md - Comprehensive documentation
• examples/03_github_workflows/05_posthog_debugging/workflow.yml - GitHub Actions workflow configuration

Key Features

• Event Fetching: Support for both event name queries (using HogQL) and specific event ID lookups
• GitHub Integration: Automatic issue creation with PostHog event data
• AI Agent Support: Generate debugging prompts for AI agents to investigate issues
• Flexible Configuration: Support for multiple PostHog hosting options (cloud, US, EU)
• Error Handling: Comprehensive error handling and detailed logging
• Documentation: Complete setup guide with examples and troubleshooting tips

Implementation Details

The PostHog example follows the same structure as the DataDog example but adapts to PostHog's API:

1. Query API: Uses PostHog's HogQL query language for flexible event filtering
2. Events API: Direct event ID lookup for specific events
3. Authentication: Uses PostHog Personal API Key
4. Issue Management: Creates GitHub issues with PostHog event details and unique identifiers
5. Agent Integration: Generates prompts for OpenHands agents to debug issues

Testing

The implementation has been tested with:

• ✅ Basic functionality tests (environment validation, identifier creation, issue formatting)
• ✅ Integration tests (full workflow with mocked APIs)
• ✅ Pre-commit hooks (type checking, linting, formatting)

Usage

# Set environment variables
export POSTHOG_API_KEY=your_posthog_api_key
export POSTHOG_PROJECT_ID=your_project_id
export GITHUB_TOKEN=your_github_token
export LLM_API_KEY=your_llm_api_key

# Run the script
python posthog_debugging.py --event-query '$exception' --repos OpenHands/OpenHands --limit 5

Or use with GitHub Actions:

- name: Debug PostHog Events
  uses: ./.github/workflows/posthog-debugging.yml
  with:
    event-query: '$exception'
    repos: 'OpenHands/OpenHands'

Documentation

The example includes comprehensive documentation covering:

• Prerequisites and setup instructions
• Environment variable configuration
• Usage examples for both CLI and GitHub Actions
• Troubleshooting guide for common issues
• PostHog API reference links

Related Work

This example is modeled after the existing DataDog debugging example in examples/03_github_workflows/04_datadog_debugging/ and provides similar functionality for PostHog users.

Checklist

• Code follows the repository's style guidelines
• Pre-commit hooks pass (type checking, linting, formatting)
• Basic functionality tested
• Integration tests pass
• Documentation is comprehensive and clear
• Commit message includes co-authorship attribution

@neubig can click here to continue refining the PR

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:1230850-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-1230850-python \
  ghcr.io/openhands/agent-server:1230850-python

All tags pushed for this build

ghcr.io/openhands/agent-server:1230850-golang-amd64
ghcr.io/openhands/agent-server:1230850-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:1230850-golang-arm64
ghcr.io/openhands/agent-server:1230850-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:1230850-java-amd64
ghcr.io/openhands/agent-server:1230850-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:1230850-java-arm64
ghcr.io/openhands/agent-server:1230850-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:1230850-python-amd64
ghcr.io/openhands/agent-server:1230850-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:1230850-python-arm64
ghcr.io/openhands/agent-server:1230850-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:1230850-golang
ghcr.io/openhands/agent-server:1230850-java
ghcr.io/openhands/agent-server:1230850-python

About Multi-Architecture Support

• Each variant tag (e.g., 1230850-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 1230850-python-amd64) are also available if needed