Langsmith Tracing Verifier

Verifies LangSmith tracing configuration and connectivity before Claude Code sessions begin collecting observability data.

When to Use This Hook

Attach this hook when you need to:

• Confirm LangSmith API keys are valid and have correct permissions before tracing starts
• Validate that project names and environment variables are properly configured
• Detect connectivity issues with the LangSmith backend early rather than losing trace data silently

Consider alternatives when:

• You use a different observability platform like Datadog or OpenTelemetry directly
• Your tracing setup is managed entirely by infrastructure-as-code and validated in CI

Quick Start

Configuration

Copy
name: langsmith-tracing-verifier
type: hook
trigger: PreToolUse
category: monitoring

Example Trigger

Copy
# Hook triggers at session start to validate tracing config
claude> "Analyze this codebase"
# Before any tool runs, the verifier checks LangSmith connectivity

Example Output

LangSmith Tracing Verifier
  TRACE_TO_LANGSMITH: true
  API Key: lsv2_pt_****...7f2a (valid format)
  Project: claude-code-project
  Connectivity: OK (latency: 142ms)
  Debug mode: disabled
Tracing verified. Traces will be sent to claude-code-project.

Core Concepts

Verification Checks Overview

Aspect	Details
API Key Format	Validates key starts with lsv2_pt_ prefix
Key Authentication	Makes a lightweight API call to confirm key is active
Project Existence	Verifies the target project exists or can be auto-created
Network Connectivity	Tests HTTPS connectivity to smith.langchain.com
Environment Variables	Confirms all required env vars are set and non-empty

Verification Workflow

Session Starts
      |
  Read Env Vars
      |
  ┌───┴────────┐
  |            |
Key Format   Vars Set?
Check          |
  |          Missing
  |          → Warn
  |
  API Ping
  /     \
OK      Fail
|        |
Enable  Disable Tracing
Tracing  + Log Warning

Configuration

Parameter	Type	Default	Description
TRACE_TO_LANGSMITH	string	"true"	Enable or disable tracing globally
CC_LANGSMITH_API_KEY	string	""	LangSmith API key (starts with lsv2_pt_)
CC_LANGSMITH_PROJECT	string	"claude-code-project"	Target project name for trace collection
CC_LANGSMITH_DEBUG	boolean	false	Enable verbose debug logging for trace pipeline
verify_on_start	boolean	true	Run verification at session start vs on-demand only

Best Practices

1. Store Keys in Environment Files - Never hardcode LangSmith API keys in hook configurations. Use .env files or secret managers and reference them via environment variables in your hook setup.

2. Use Project Naming Conventions - Name LangSmith projects to reflect the repository and environment (e.g., myapp-staging). The verifier can enforce naming patterns to keep your trace data organized.

3. Enable Debug Mode Selectively - The CC_LANGSMITH_DEBUG flag generates verbose output useful for diagnosing missing traces. Enable it only during troubleshooting to avoid cluttering your session output.

4. Set Up Graceful Degradation - Configure the verifier to warn but not block when LangSmith is unreachable. Losing tracing should not prevent productive coding sessions.

5. Rotate API Keys Regularly - LangSmith API keys should be rotated on a schedule. The verifier will catch expired keys immediately at session start rather than after hours of lost traces.

Common Issues

1. Key Format Valid but Revoked - A key matching lsv2_pt_ format may still be revoked server-side. The verifier makes an authenticated ping to catch this, but network timeouts can mask the check. Increase timeout if on slow connections.

2. Project Auto-Creation Fails - Some LangSmith plans restrict project creation via API. If the verifier cannot find or create the target project, manually create it in the LangSmith dashboard first.

3. Proxy Blocking HTTPS to LangSmith - Corporate proxies may block outbound connections to smith.langchain.com. Configure HTTPS_PROXY in your environment or whitelist the domain with your network team.