PostHog 완벽 가이드 2026: 오픈소스 프로덕트 분석 & AI 옵저버빌리티 플랫폼 입문

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/posthog/posthog/HEAD/bin/deploy-hobby)"

# docker-compose.yml
version: '3.8'

services:
  posthog:
    image: posthog/posthog:latest
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgres://posthog:posthog@db:5432/posthog
      - REDIS_URL=redis://redis:6379/
    depends_on:
      - db
      - redis

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: posthog
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7

volumes:
  pgdata:

# 서비스 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f posthog

npm install posthog-js

import posthog from 'posthog-js';

posthog.init('YOUR_POSTHOG_API_KEY', {
  api_host: 'https://us.posthog.com',  // 자체 호스팅은 http://your-server:8000으로 변경
  autocapture: true,  // 모든 클릭, 페이지 뷰 등 자동 캡처
});

// 커스텀 이벤트 수동 전송
posthog.capture('user_signed_up', {
  method: 'email',
  plan: 'free',
});

// 사용자 설정 (로그인 시 호출)
posthog.identify('user-unique-id-123', {
  email: 'developer@example.com',
  name: '홍길동',
});

pip install posthog

from posthog import Posthog

# 초기화 (API 키는 환경변수 저장 권장)
posthog = Posthog(
    project_api_key='YOUR_PROJECT_API_KEY',
    host='https://us.posthog.com'
)

# 이벤트 캡처
posthog.capture(
    distinct_id='user-unique-id-123',
    event='payment_completed',
    properties={
        'amount': 99.00,
        'currency': 'USD',
        'payment_method': 'stripe',
    }
)

# 사용자 속성 설정
posthog.identify(
    distinct_id='user-unique-id-123',
    properties={
        'email': 'developer@example.com',
        'plan': 'pro',
        'company': 'TechCorp',
    }
)

# 클라이언트 종료 (앱 종료 시)
posthog.shutdown()

npm install posthog-js posthog-node

// components/PostHogProvider.tsx
import { PostHogProvider as PHProvider } from 'posthog-js/react';
import { useEffect, useState } from 'react';
import posthog from 'posthog-js';

export function PostHogProvider({ children }: { children: React.ReactNode }) {
  const [clientReady, setClientReady] = useState(false);

  useEffect(() => {
    posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.posthog.com',
      person_profiles: 'identified_only',
    });
    setClientReady(true);
  }, []);

  if (!clientReady) return null;
  return <PHProvider client={posthog}>{children}</PHProvider>;
}

// app/layout.tsx
import { PostHogProvider } from '@/components/PostHogProvider';

export default function RootLayout({ children }) {
  return (
    <html lang="zh">
      <body>
        <PostHogProvider>{children}</PostHogProvider>
      </body>
    </html>
  );
}

// app/page.tsx
'use client';
import { usePostHog } from 'posthog-js/react';

export default function HomePage() {
  const posthog = usePostHog();

  return (
    <button onClick={() => {
      posthog.capture('cta_clicked', {
        cta_text: '무료 체험 시작하기',
        page: 'homepage',
      });
    }}>
      무료 체험 시작하기
    </button>
  );
}

-- PostHog는 SQL 직접 쿼리 지원 (ClickHouse)
SELECT
    event,
    COUNT(DISTINCT distinct_id) as users
FROM events
WHERE event IN ('user_signed_up', 'feature_activated', 'payment_completed')
  AND timestamp > now() - INTERVAL 30 DAY
GROUP BY event
ORDER BY timestamp

posthog.init('YOUR_API_KEY', {
  api_host: 'https://us.posthog.com',
  session_recording: {
    maskAllInputs: false,  // 입력 내용 마스킹 안 함 (개인정보 민감한 상황은 true로)
    recordCrossOriginIframes: true,
  },
});

// 사용자가 동일 요소를 빠르게 5회 이상 연속 클릭하면 rage click 이벤트 트리거
posthog.onFeatureFlags(() => {
  posthog.capture('rageclick', {
    element: document.activeElement.tagName,
    page: window.location.pathname,
  });
});

// 특정 기능이 사용자에게 개방되었는지 확인
posthog.onFeatureFlags(() => {
  const newDashboard = posthog.getFeatureFlag('new-dashboard');

  if (newDashboard) {
    // 신규 대시보드 표시
    renderNewDashboard();
  } else {
    // 기존 버전 유지
    renderOldDashboard();
  }
});

// 사용자 속성 기반 타겟팅
posthog.capture('feature_viewed', {
  $feature_flag: 'beta-search',
  $feature_flag_response: true,
});

// 실험 코드
posthog.onFeatureFlags(() => {
  const experiment = posthog.getFeatureFlag('landing-page-test');

  if (experiment === 'variant-a') {
    showVariantA();
  } else if (experiment === 'variant-b') {
    showVariantB();
  }

  // 실험 노출 기록
  posthog.capture('experiment_exposure', {
    $feature_flag: 'landing-page-test',
    variant: experiment,
  });
});

import posthog from 'posthog-js';

posthog.init('YOUR_API_KEY', {
  api_host: 'https://us.posthog.com',
  capture_performance: true,
});

// uncaught errors 자동 캡처
window.addEventListener('error', (event) => {
  posthog.capture('frontend_error', {
    error_message: event.message,
    error_url: event.filename,
    error_line: event.lineno,
    error_col: event.colno,
    stack: event.error?.stack,
  });
});

// unhandled promise rejections 캡처
window.addEventListener('unhandledrejection', (event) => {
  posthog.capture('promise_rejection', {
    error_message: event.reason?.message || String(event.reason),
  });
});

pip install posthog openai

from posthog import Posthog
import openai

posthog = Posthog('YOUR_API_KEY', host='https://us.posthog.com')

def generate_with_tracking(user_id: str, prompt: str):
    import time
    start = time.time()

    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )

    latency = time.time() - start
    tokens_used = response.usage.total_tokens

    # LLM 호출 추적
    posthog.capture(
        distinct_id=user_id,
        event='llm_call_completed',
        properties={
            'model': 'gpt-4',
            'prompt_length': len(prompt),
            'response_length': len(response.choices[0].message.content),
            'tokens_used': tokens_used,
            'latency_ms': latency * 1000,
            'success': True,
        }
    )

    return response

from langchain.callbacks import PostHogCallbackHandler

handler = PostHogCallbackHandler(
    api_key='YOUR_API_KEY',
    host='https://us.posthog.com',
    distinct_id='user-123',
)

# 체인에서 사용
chain = LLMChain(llm=llm, prompt=prompt, callbacks=[handler])
result = chain.run("안녕하세요, PostHog를 소개해 주세요")

// .mcp.json
{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": ["-y", "@posthog/mcp"],
      "env": {
        "POSTHOG_API_KEY": "phc_your_api_key",
        "POSTHOG_PERSONAL_API_KEY": "phx_your_personal_key",
        "POSTHOG_PROJECT_ID": "12345",
        "POSTHOG_API_HOST": "https://us.posthog.com"
      }
    }
  }
}