TraceKit CLI Integration

The fastest and easiest way to integrate distributed tracing and health monitoring into your application. One command does everything - no manual configuration required.

🚀 ONE COMMAND DOES EVERYTHING

tracekit init

That's it! This single command will:

• ✅ Detect your framework automatically
• ✅ Create your free account (email verification)
• ✅ Generate and save API key to .env
• ✅ Send test trace to verify setup
• ✅ Optionally install SDK
• ✅ Optionally configure health checks
• ✅ Optionally configure webhooks

What You Get

Supported Languages

• PHP (GemVC, Laravel, Symfony, custom frameworks)
• Node.js (Express, NestJS, custom)
• Python (Django, Flask, FastAPI)
• Go (Gin, Echo, Chi)
• Java (Spring Boot)
• Ruby (Rails, Sinatra)

Installation

macOS / Linux

# Download and install
curl -fsSL https://raw.githubusercontent.com/Tracekit-Dev/cli/main/install.sh | sh

# Or with Homebrew
brew install Tracekit-Dev/tap/tracekit

Windows

# Download from GitHub releases
# https://github.com/Tracekit-Dev/cli/releases/latest/download/tracekit-windows-amd64.exe

Verify Installation

tracekit --version
# Output: tracekit version 1.0.0

Quick Start

One-Command Setup

Simply run tracekit init in your project directory:

cd your-project
tracekit init

What Happens Automatically:

• ✅ Step 1: Detects your framework (GemVC, Laravel, Express, etc.)
• ✅ Step 2: Creates your account (email + 6-digit verification code)
• ✅ Step 3: Generates API key
• ✅ Step 4: Saves configuration to .env file
• ✅ Step 5: Sends test trace to verify setup
• ✅ Step 6: Shows integration status
• ✅ Step 7: Optionally installs SDK (you choose Y/n)
• ✅ Step 8: Optionally sets up health checks (you choose Y/n)
• ✅ Step 9: Optionally configures webhooks (you choose Y/n)

Complete Interactive Flow Example:

┌─────────────────────────────────────────────────┐
│  TraceKit - Distributed Tracing & Monitoring    │
└─────────────────────────────────────────────────┘

🔍 Framework Detection
✓ Detected: gemvc (php)

📧 Account Creation
Enter your email: [email protected]
✓ Verification code sent to [email protected]

🔑 Email Verification
Enter 6-digit code: 123456
✓ Account created!
✓ API key saved to .env

🧪 Sending Test Trace
✓ Verifying your setup...
✓ Test trace sent successfully!

📊 Integration Status
  Status:         Active ✓
  Service:        my-app
  Organization:   Quantum Labs
  Plan:           Hacker (Free - 200k traces/month)

📦 SDK Installation (Optional)
Detected language: PHP
Recommended SDK: OpenTelemetry PHP

Install OpenTelemetry PHP now?
   Y     = Install recommended SDK
   n     = Skip installation
   other = Show all available SDKs

Your choice: Y

✓ Installing OpenTelemetry PHP...
✓ SDK installed successfully!

🏥 Health Check Setup (Optional)
Set up health check monitoring for your service?
  Monitor your service health with automatic alerts
  • Pull-based: TraceKit pings your endpoint
  • Push-based: Your service sends heartbeats

Configure health check now? (Y/n): Y

Choose health check type:
  [1] Pull-based - TraceKit pings your endpoint (recommended)
  [2] Push-based - Your service sends heartbeats
  [0] Skip for now

Select type (0-2): 2

✓ Push-based health check configured!
  Heartbeat interval: 60 seconds
  Failure threshold: 3 consecutive failures
  Send heartbeats with: POST /v1/health/heartbeat

═══════════════════════════════════════════════════

🎉 Setup Complete!

Dashboard:  https://app.tracekit.dev
API Key:    ctxio_a1b2...xyz6 (saved to .env)
Service:    my-app
Plan:       Hacker (Free - 200k traces/month)

CLI Commands

tracekit init

Initialize TraceKit monitoring for your project.

# Interactive mode (recommended)
tracekit init

# With options
tracekit init [email protected] --service=my-app

# Auto-confirm prompts (for CI/CD)
tracekit init --auto-confirm

# JSON output
tracekit init --json

Options:

• --email - Your email address
• --service - Service name (default: current directory name)
• --source - Partner/framework code for attribution (e.g., gemvc, laravel, nestjs) - helps us track referrals and provide proper attribution to partners
• --auto-confirm - Skip confirmation prompts
• --json - Output JSON for programmatic usage

tracekit health setup

Configure health check monitoring.

# Setup push-based heartbeat
tracekit health setup --type=push --interval=60

# Setup pull-based endpoint check
tracekit health setup --type=pull --url=https://api.example.com/health

# With options
tracekit health setup \
  --type=push \
  --interval=60 \
  --threshold=3 \
  --grace-period=30

Options:

• --type - Check type: push (heartbeat) or pull (endpoint)
• --interval - Heartbeat interval in seconds (default: 60)
• --threshold - Consecutive failures before alert (default: 3)
• --grace-period - Grace period in seconds (default: 30)
• --url - Endpoint URL (for pull-based checks)

tracekit health list

List all configured health checks.

# List health checks
tracekit health list

# JSON output
tracekit health list --json

Output:

┌───────────────────────────────────────────┐
│  Health Checks - gemvc-api                │
└───────────────────────────────────────────┘

  NAME       TYPE   STATUS    UPTIME   FAILURES
  heartbeat  push   healthy   99.95%   0/3

  Last check: 30 seconds ago
  Next check: in 30 seconds

tracekit status

Check integration status.

tracekit status

Output:

┌───────────────────────────────────────────┐
│  TraceKit Status                          │
└───────────────────────────────────────────┘

  Status:         Active ✓
  Service:        gemvc-api
  Organization:   Quantum Labs
  Plan:           Hacker (Free)

  Traces:         1,234 / 200,000 this month
  Health Checks:  1 active
  Alerts:         0 active

  Dashboard: https://app.tracekit.dev

tracekit webhook create

Create a new webhook to receive event notifications.

# Interactive mode
tracekit webhook create

# With options
tracekit webhook create \
  --name="Production Alerts" \
  --url="https://your-app.com/webhook" \
  --events="health_check.failed,health_check.recovered,alert.triggered"

Interactive Flow:

• Enter webhook name
• Enter webhook URL (HTTPS required for production, HTTP allowed for localhost)
• Enter description (optional)
• Select event types to subscribe to

Available Event Types:

• health_check.failed - Health check failed
• health_check.recovered - Health check recovered
• alert.triggered - Alert rule triggered
• alert.resolved - Alert resolved
• trace.error - Trace contains error
• anomaly.detected - Anomaly detected

tracekit webhook list

List all configured webhooks.

# List webhooks
tracekit webhook list

# JSON output
tracekit webhook list --json

tracekit webhook delete

Delete a webhook by its ID.

# Delete a webhook by ID
tracekit webhook delete <webhook-id>

# Example
tracekit webhook delete 550e8400-e29b-41d4-a716-446655440000

tracekit upgrade

Upgrade your subscription plan directly from the CLI. See the Subscription & Upgrade section below for details.

Subscription & Upgrade

Upgrade your TraceKit subscription plan directly from the CLI without visiting the dashboard.

Command

tracekit upgrade

How It Works

1. Check Current Plan: CLI fetches your current subscription and usage
2. Generate Token: Creates a secure one-time upgrade token (15-minute expiry)
3. Open Browser: Opens your browser to the upgrade page with token authentication
4. Select Plan: Choose your new plan and complete Stripe checkout
5. Callback: Success page triggers callback to CLI localhost server (port 17834)
6. Confirmation: CLI receives instant confirmation or polls for status
7. Updated Plan: Displays your new plan and trace limits

Available Plans

You can upgrade from the free Hacker plan to:

• Startup Plan: Higher trace limits for growing applications
• Pro Plan: Advanced features and unlimited traces
• Enterprise Plan: Custom solutions - contact [email protected]

Webhook Management

Webhooks allow you to receive real-time notifications when events occur in your TraceKit account.

Create a Webhook

Use the interactive webhook creation flow:

tracekit webhook create

The CLI will prompt you for:

1. Webhook Name: A descriptive name for the webhook (e.g., "Production Alerts")
2. URL: Your endpoint to receive webhook events (HTTPS required for production)
3. Description: Optional description of what this webhook is used for
4. Event Types: Select which events to receive notifications for

Example Output:

🔗 Webhook name: Production Alerts
📡 Webhook URL (HTTPS required, or HTTP for localhost): https://api.example.com/webhooks
📝 Description (optional): Alerts for production environment

📋 Available event types:
  1. health_check.failed
  2. health_check.recovered
  3. alert.triggered
  4. alert.resolved
  5. trace.error
  6. anomaly.detected

🎯 Select events (comma-separated numbers, e.g., 1,3,4): 1,2,3

✅ Webhook created successfully!

📦 Webhook ID: 550e8400-e29b-41d4-a716-446655440000
🔗 Name: Production Alerts
📡 URL: https://api.example.com/webhooks

⚠️  IMPORTANT: Save this secret securely!
🔐 Secret: whsec_7k3n9m2p4q8r1s5t6v9w0x2y4z

This secret will only be shown once. You'll need it to verify webhook signatures.

Example verification code:
  const crypto = require('crypto');
  const signature = req.headers['x-webhook-signature'];
  const secret = 'whsec_7k3n9m2p4q8r1s5t6v9w0x2y4z';
  const hash = crypto.createHmac('sha256', secret)
                    .update(JSON.stringify(req.body))
                    .digest('hex');
  const expected = 'sha256=' + hash;
  if (signature === expected) { /* verified */ }

📋 Subscribed events:
  ✓ health_check.failed
  ✓ health_check.recovered
  ✓ alert.triggered

List Webhooks

View all configured webhooks:

# List all webhooks
tracekit webhook list

# JSON output
tracekit webhook list --json

Delete a Webhook

Remove a webhook by its ID:

# Delete a webhook
tracekit webhook delete <webhook-id>

# Example
tracekit webhook delete 550e8400-e29b-41d4-a716-446655440000

Webhook Events

TraceKit can notify your application about these events:

Health Check Monitoring

Push-Based (Heartbeat)

Send heartbeats every 60 seconds to indicate service health.

# Send manual heartbeat
tracekit health heartbeat

# Or use cron (every minute)
* * * * * /usr/local/bin/tracekit health heartbeat

Pull-Based (Endpoint Check)

TraceKit periodically pings your health endpoint.

# Setup endpoint check
tracekit health setup \
  --type=pull \
  --url=https://api.gemvc.io/health \
  --interval=60

Your endpoint should return:

{
  "status": "healthy",
  "timestamp": "2025-12-02T12:00:00Z"
}

Alert Configuration

Alerts are automatically configured:

• Consecutive Failures: 3 failures trigger alert
• Grace Period: 30 seconds after expected heartbeat
• Email Notifications: Sent to your registered email
• Severity: Critical for health check failures

Configuration

Environment Variables

TraceKit automatically adds to .env file:

# TraceKit Configuration
TRACEKIT_API_KEY=ctxio_your_api_key_here
TRACEKIT_ENDPOINT=https://app.tracekit.dev
TRACEKIT_SERVICE_NAME=my-app
TRACEKIT_ENABLED=true
TRACEKIT_CODE_MONITORING_ENABLED=true

Configuration Values

• TRACEKIT_API_KEY - Your unique API key for authentication
• TRACEKIT_ENDPOINT - TraceKit API base URL
• TRACEKIT_SERVICE_NAME - Your service/application name
• TRACEKIT_ENABLED - Enable/disable tracing (true/false)
• TRACEKIT_CODE_MONITORING_ENABLED - Enable live debugging features (true/false)

Best Practices

1. Framework Integration

Bundle CLI with framework:

{
  "require": {
    "gemvc/framework": "^1.0",
    "tracekit/cli": "^1.0"
  }
}

2. Health Monitoring

Use push-based for web apps:

// Send heartbeat on every request (cached to once per minute)
register_shutdown_function(function() {
    $lastSent = apcu_fetch('tracekit_heartbeat_last_sent');
    if (time() - $lastSent >= 60) {
        exec('tracekit health heartbeat > /dev/null 2>&1 &');
        apcu_store('tracekit_heartbeat_last_sent', time());
    }
});

Use pull-based for APIs:

tracekit health setup --type=pull --url=https://api.example.com/health

3. Security

Never commit .env:

.env
.tracekit.json

Use separate keys per environment:

# Production
TRACEKIT_API_KEY=ctxio_prod_...

# Staging
TRACEKIT_API_KEY=ctxio_staging_...

Troubleshooting

Common Issues

1. "tracekit: command not found"

Cause: CLI not in PATH

Solution:

# Add to PATH
export PATH="$HOME/.tracekit/bin:$PATH"

# Or reinstall
curl -fsSL https://raw.githubusercontent.com/Tracekit-Dev/cli/main/install.sh | sh

2. "Email verification failed"

Cause: Code expired or incorrect

Solution:

• Check spam folder for verification email
• Request new code (start tracekit init again)
• Ensure code is entered within 15 minutes

3. "Health check not receiving heartbeats"

Cause: Heartbeat not being sent

Solution:

# Test manual heartbeat
tracekit health heartbeat

# Check if API key is set in .env
echo $TRACEKIT_API_KEY

# Or view your .env file
cat .env | grep TRACEKIT

Debug Mode

# Enable debug output for troubleshooting
export TRACEKIT_DEBUG=1
tracekit init

# The CLI will show verbose output during execution

Next Steps