Merge pull request #5 from doneyli/feature/langfuse-cloud-support

Add Langfuse Cloud support

Author: doneyli

README.md

@@ -1,22 +1,50 @@
 # Claude Code + Langfuse: Session Observability Template
 
-Self-hosted Langfuse for capturing every Claude Code conversation — prompts, responses, tool calls, and session grouping.
+Capture every Claude Code conversation — prompts, responses, tool calls, and session grouping — using Langfuse Cloud or a self-hosted instance.
 
-This template provides a complete, production-ready setup for observing your Claude Code sessions using Langfuse. Everything runs locally in Docker, with automatic session tracking and incremental state management.
+This template provides a complete, production-ready setup for observing your Claude Code sessions using Langfuse. Choose between **Langfuse Cloud** (zero infrastructure) or **self-hosted** (everything runs locally in Docker), with automatic session tracking and incremental state management.
 
 **Read the full story:** [I Built My Own Observability for Claude Code](https://doneyli.substack.com/p/i-built-my-own-observability-for) — why I built this, how it works, and screenshots of the setup in action.
 
-## Prerequisites
+## Choose Your Setup
 
-- Docker and Docker Compose
-- Python 3.11 or higher
-- Claude Code CLI (desktop or terminal)
-- 4-6GB available RAM
-- 2-5GB available disk space
+| | Langfuse Cloud | Self-Hosted |
+|---|---|---|
+| **Infrastructure** | None (fully managed) | Docker on your machine |
+| **Prerequisites** | Python 3.11+ | Python 3.11+, Docker, 4-6GB RAM, 2-5GB disk |
+| **Setup time** | ~2 minutes | ~5 minutes |
+| **Data location** | Langfuse Cloud (EU or US) | Your machine only |
+| **Cost** | Free tier available | Free (self-hosted) |
 
-## Quick Start
+## Quick Start — Option A: Langfuse Cloud
 
-Follow these steps to get Langfuse observability running in under 5 minutes:
+Use this if you have (or want to create) a [Langfuse Cloud](https://cloud.langfuse.com) account. No Docker required.
+
+**Prerequisites:** Python 3.11+, Claude Code CLI, a Langfuse Cloud account with API keys.
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/doneyli/claude-code-langfuse-template.git
+   cd claude-code-langfuse-template
+   ```
+
+2. **Install the hook (cloud mode)**
+   ```bash
+   ./scripts/install-hook.sh --cloud
+   ```
+   You'll be prompted for your public key, secret key, and region (EU/US/custom).
+
+3. **Verify the setup**
+   ```bash
+   ./scripts/validate-setup.sh --cloud --post
+   ```
+   Then start a Claude Code conversation — traces will appear in your Langfuse Cloud dashboard.
+
+## Quick Start — Option B: Self-Hosted
+
+Use this to run everything locally in Docker. No external accounts needed.
+
+**Prerequisites:** Docker and Docker Compose, Python 3.11+, Claude Code CLI, 4-6GB RAM, 2-5GB disk.
 
 1. **Clone the repository**
    ```bash
@@ -188,10 +216,10 @@ The Langfuse hook runs as a Claude Code **Stop hook** — it executes after each
        │
        │ HTTP POST
        ▼
-┌──────────────────┐
-│ Langfuse API     │
-│ (localhost:3050) │
-└──────┬───────────┘
+┌──────────────────────────────┐
+│ Langfuse API                 │
+│ (localhost:3050 or Cloud)    │
+└──────┬───────────────────────┘
        │
        ▼
 ┌──────────────────────────┐
@@ -228,6 +256,10 @@ To opt out for a specific project:
 
 See `settings-examples/project-opt-out.json` for a complete example.
 
+### Cloud Settings Example
+
+If you're using Langfuse Cloud and want to see or tweak the generated configuration, see `settings-examples/cloud-settings.json`.
+
 ### Environment Variables
 
 All configuration is managed through environment variables in `~/.claude/settings.json`:
@@ -389,6 +421,25 @@ lsof -i :3050
 # Either stop that service, or change the Langfuse port in docker-compose.yml
 ```
 
+### Cloud: API key rejected
+
+**Symptom:** Traces don't appear in Langfuse Cloud, hook logs show 401/403 errors
+
+**Check:**
+1. Keys must start with `pk-lf-` (public) and `sk-lf-` (secret)
+2. Verify keys match the correct project in your Langfuse Cloud dashboard
+3. Ensure `LANGFUSE_HOST` matches your region (`https://cloud.langfuse.com` for EU, `https://us.cloud.langfuse.com` for US)
+4. Re-run: `./scripts/install-hook.sh --cloud`
+
+### Cloud: Cannot reach Langfuse Cloud
+
+**Symptom:** `validate-setup.sh --cloud --post` warns that the API is not reachable
+
+**Check:**
+1. Verify internet connectivity: `curl https://cloud.langfuse.com/api/public/health`
+2. Check for proxy/firewall blocking outbound HTTPS
+3. If using a custom URL, verify it's correct
+
 ### Traces not appearing
 
 **Symptom:** Langfuse UI shows no traces after conversations
@@ -397,8 +448,9 @@ lsof -i :3050
 1. Is `TRACE_TO_LANGFUSE=true` in `~/.claude/settings.json`?
 2. Are the API keys correct?
 3. Check hook logs: `tail -f ~/.claude/state/langfuse_hook.log`
-4. Verify Docker services are running: `docker compose ps`
-5. Test Langfuse API: `curl http://localhost:3050/api/public/health`
+4. **Self-hosted:** Verify Docker services are running: `docker compose ps`
+5. **Self-hosted:** Test API: `curl http://localhost:3050/api/public/health`
+6. **Cloud:** Test API: `curl https://cloud.langfuse.com/api/public/health`
 
 ### Hook runs slowly
 
@@ -459,10 +511,16 @@ docker compose up -d
 
 ### Security
 
+**Self-hosted:**
 - All services run on `localhost` (not exposed to network)
 - Credentials are generated randomly on first setup
 - `.env` file is git-ignored (never commit credentials)
-- No telemetry is sent to external services (Langfuse self-hosted)
+- No telemetry is sent to external services
+
+**Cloud:**
+- Traces are sent to Langfuse Cloud (EU or US region)
+- API keys are stored in `~/.claude/settings.json` (not committed to git)
+- Review [Langfuse's security & privacy documentation](https://langfuse.com/security) for data handling details
 
 ## Customization Ideas
 

scripts/install-hook.sh

@@ -7,30 +7,107 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
+# Parse flags
+CLOUD_MODE=false
+if [[ "${1:-}" == "--cloud" ]]; then
+    CLOUD_MODE=true
+fi
+
 echo "====================================="
 echo "Claude Code Langfuse Hook Installer"
+if [ "$CLOUD_MODE" = true ]; then
+    echo "  (Langfuse Cloud mode)"
+fi
 echo "====================================="
 echo ""
 
-# Check if .env exists
-if [ ! -f .env ]; then
-    echo -e "${RED}Error: .env file not found${NC}"
-    echo "Please run ./scripts/generate-env.sh first"
-    exit 1
-fi
+if [ "$CLOUD_MODE" = true ]; then
+    # --- Cloud mode: prompt for credentials interactively ---
+    echo "Setting up Langfuse Cloud integration."
+    echo ""
 
-# Extract credentials from .env (safer than source - avoids code injection)
-get_env_value() {
-    grep "^$1=" .env 2>/dev/null | cut -d= -f2- | head -1
-}
+    # Prompt for public key
+    read -rp "Enter your Langfuse public key (pk-lf-...): " LANGFUSE_PUBLIC_KEY
+    if [[ -z "$LANGFUSE_PUBLIC_KEY" ]]; then
+        echo -e "${RED}Error: Public key cannot be empty${NC}"
+        exit 1
+    fi
+    if [[ ! "$LANGFUSE_PUBLIC_KEY" =~ ^pk-lf- ]]; then
+        echo -e "${RED}Error: Public key must start with 'pk-lf-'${NC}"
+        exit 1
+    fi
 
-LANGFUSE_INIT_PROJECT_PUBLIC_KEY=$(get_env_value "LANGFUSE_INIT_PROJECT_PUBLIC_KEY")
-LANGFUSE_INIT_PROJECT_SECRET_KEY=$(get_env_value "LANGFUSE_INIT_PROJECT_SECRET_KEY")
+    # Prompt for secret key
+    read -rp "Enter your Langfuse secret key (sk-lf-...): " LANGFUSE_SECRET_KEY
+    if [[ -z "$LANGFUSE_SECRET_KEY" ]]; then
+        echo -e "${RED}Error: Secret key cannot be empty${NC}"
+        exit 1
+    fi
+    if [[ ! "$LANGFUSE_SECRET_KEY" =~ ^sk-lf- ]]; then
+        echo -e "${RED}Error: Secret key must start with 'sk-lf-'${NC}"
+        exit 1
+    fi
 
-if [ -z "$LANGFUSE_INIT_PROJECT_PUBLIC_KEY" ] || [ -z "$LANGFUSE_INIT_PROJECT_SECRET_KEY" ]; then
-    echo -e "${RED}Error: Could not read API keys from .env${NC}"
-    echo "Ensure LANGFUSE_INIT_PROJECT_PUBLIC_KEY and LANGFUSE_INIT_PROJECT_SECRET_KEY are set"
-    exit 1
+    # Prompt for region
+    echo ""
+    echo "Choose your Langfuse region:"
+    echo "  1) EU  (cloud.langfuse.com)"
+    echo "  2) US  (us.cloud.langfuse.com)"
+    echo "  3) Custom URL"
+    read -rp "Selection [1]: " REGION_CHOICE
+    REGION_CHOICE="${REGION_CHOICE:-1}"
+
+    case "$REGION_CHOICE" in
+        1)
+            LANGFUSE_HOST="https://cloud.langfuse.com"
+            ;;
+        2)
+            LANGFUSE_HOST="https://us.cloud.langfuse.com"
+            ;;
+        3)
+            read -rp "Enter your Langfuse URL (e.g. https://my-langfuse.example.com): " LANGFUSE_HOST
+            if [[ -z "$LANGFUSE_HOST" ]]; then
+                echo -e "${RED}Error: URL cannot be empty${NC}"
+                exit 1
+            fi
+            ;;
+        *)
+            echo -e "${RED}Error: Invalid selection${NC}"
+            exit 1
+            ;;
+    esac
+
+    echo ""
+    echo -e "${GREEN}✓ Cloud credentials configured${NC}"
+    echo "  Host: $LANGFUSE_HOST"
+    echo "  Public Key: $LANGFUSE_PUBLIC_KEY"
+    echo ""
+
+else
+    # --- Self-hosted mode: read from .env ---
+    # Check if .env exists
+    if [ ! -f .env ]; then
+        echo -e "${RED}Error: .env file not found${NC}"
+        echo "Please run ./scripts/generate-env.sh first"
+        echo ""
+        echo "Or use --cloud for Langfuse Cloud: ./scripts/install-hook.sh --cloud"
+        exit 1
+    fi
+
+    # Extract credentials from .env (safer than source - avoids code injection)
+    get_env_value() {
+        grep "^$1=" .env 2>/dev/null | cut -d= -f2- | head -1
+    }
+
+    LANGFUSE_PUBLIC_KEY=$(get_env_value "LANGFUSE_INIT_PROJECT_PUBLIC_KEY")
+    LANGFUSE_SECRET_KEY=$(get_env_value "LANGFUSE_INIT_PROJECT_SECRET_KEY")
+    LANGFUSE_HOST="http://localhost:3050"
+
+    if [ -z "$LANGFUSE_PUBLIC_KEY" ] || [ -z "$LANGFUSE_SECRET_KEY" ]; then
+        echo -e "${RED}Error: Could not read API keys from .env${NC}"
+        echo "Ensure LANGFUSE_INIT_PROJECT_PUBLIC_KEY and LANGFUSE_INIT_PROJECT_SECRET_KEY are set"
+        exit 1
+    fi
 fi
 
 # Find Python 3.11+
@@ -128,9 +205,9 @@ if "hooks" not in settings:
 
 # Add environment variables
 settings["env"]["TRACE_TO_LANGFUSE"] = "true"
-settings["env"]["LANGFUSE_PUBLIC_KEY"] = "$LANGFUSE_INIT_PROJECT_PUBLIC_KEY"
-settings["env"]["LANGFUSE_SECRET_KEY"] = "$LANGFUSE_INIT_PROJECT_SECRET_KEY"
-settings["env"]["LANGFUSE_HOST"] = "http://localhost:3050"
+settings["env"]["LANGFUSE_PUBLIC_KEY"] = "$LANGFUSE_PUBLIC_KEY"
+settings["env"]["LANGFUSE_SECRET_KEY"] = "$LANGFUSE_SECRET_KEY"
+settings["env"]["LANGFUSE_HOST"] = "$LANGFUSE_HOST"
 
 # Add Stop hook if not already present
 if "Stop" not in settings["hooks"]:
@@ -179,15 +256,29 @@ echo ""
 echo "Configuration:"
 echo "  Hook: $HOOK_DEST"
 echo "  Settings: $SETTINGS_FILE"
-echo "  Host: http://localhost:3050"
-echo "  Public Key: $LANGFUSE_INIT_PROJECT_PUBLIC_KEY"
+echo "  Host: $LANGFUSE_HOST"
+echo "  Public Key: $LANGFUSE_PUBLIC_KEY"
 echo ""
-echo "Verification steps:"
-echo "  1. Ensure Docker is running"
-echo "  2. Start Langfuse: docker compose up -d"
-echo "  3. Wait 30-60 seconds for services to initialize"
-echo "  4. Start a Claude Code conversation"
-echo "  5. Check traces at http://localhost:3050"
+
+if [ "$CLOUD_MODE" = true ]; then
+    echo "Verification steps:"
+    echo "  1. Start a Claude Code conversation"
+    echo "  2. Check traces at $LANGFUSE_HOST"
+    echo ""
+    echo "Optional: Run validation"
+    echo "  ./scripts/validate-setup.sh --cloud --post"
+else
+    echo "Verification steps:"
+    echo "  1. Ensure Docker is running"
+    echo "  2. Start Langfuse: docker compose up -d"
+    echo "  3. Wait 30-60 seconds for services to initialize"
+    echo "  4. Start a Claude Code conversation"
+    echo "  5. Check traces at http://localhost:3050"
+    echo ""
+    echo "Optional: Run validation"
+    echo "  ./scripts/validate-setup.sh --post"
+fi
+
 echo ""
 echo "Debug commands:"
 echo "  View hook logs: tail -f ~/.claude/state/langfuse_hook.log"