Staging & Production Environments

Application Environments

Every app in Telemetry Kit starts in Staging mode, giving you a safe sandbox to test your integration before going live. When you're ready, promote your app to Production with a single click.

Why Staging First? Testing telemetry in staging ensures your events are correctly formatted, your privacy settings work as expected, and you're not accidentally polluting production data with test events.

Environment Comparison

Feature	Staging	Production
Events per month	1,000	Based on your tier
Data retention	30 days	Based on your tier
API keys	Unique per app	Same as staging
HMAC secret	Unique per app	Same as staging
Ingest endpoint	Same URL	Same URL
Dashboard analytics	Limited	Full analytics
Promotion	One-click to production	N/A (permanent)

How It Works

Create Your App

When you register a new app in the Telemetry Kit Dashboard, it automatically starts in Staging mode.

// Your credentials work immediately
let telemetry = TelemetryKit::builder()
    .org_id("your-org-id")
    .app_id("your-app-id")
    .api_key("your-api-key")
    .hmac_secret("your-hmac-secret")
    .endpoint("https://api.telemetry-kit.dev")
    .build()?;

Test in Staging

Use your staging environment to:

Verify event formats are correct
Test privacy controls (DNT, consent)
Debug authentication (HMAC signatures)
Experiment with different event types

// Send test events
telemetry.track_event("test_event", |event| {
    event
        .property("environment", "staging")
        .property("test", true)
        .success(true)
}).await?;

Staging Limits: You can send up to 1,000 events per month in staging. This is intentionally limited to encourage testing, not production use.

Promote to Production

When you're ready to go live:

Go to your Dashboard
Select your app
Click "Promote to Production"
Confirm the permanent action

No Code Changes Required

After promotion, your existing code works exactly the same:

Same API keys
Same HMAC secret
Same ingest endpoint URL
Same SDK configuration

The only thing that changes is your limits and data retention - both now match your subscription tier.

Staging vs Production Indicator

Your dashboard shows which environment each app is in:

Staging - Yellow badge with test tube icon
Production - Green badge with rocket icon

When viewing an app in staging, you'll also see:

Current event usage (e.g., "847 / 1,000")
Usage progress bar (turns yellow at 70%, red at 90%)
"Promote to Production" button

What Happens on Promotion

When you promote an app to production:

Environment changes from staging to production
All staging events are deleted - you start fresh
Limits increase to match your subscription tier
Data retention extends based on your plan
Full analytics unlock in your dashboard

Promotion is Permanent You cannot demote an app back to staging. This is intentional - production apps contain real user data that shouldn't be mixed with test data.

Staging Limits & Retention

Event Limits

1,000 events per month (resets on the 1st)
Events beyond the limit are rejected with HTTP 429
Usage counter visible in your dashboard

Data Retention

30 days for all staging events
Events older than 30 days are automatically deleted
This cleanup runs daily

What Counts as an Event?

Each item in your events array counts as one event:

{
  "events": [
    { "event": { "type": "command_executed" } },  // 1 event
    { "event": { "type": "error_occurred" } }      // 2 events total
  ]
}

Best Practices

1. Test All Event Types

Before promoting, send examples of every event type your app will generate:

// Test command tracking
telemetry.track_command("build", |e| e.success(true)).await?;
 
// Test error tracking
telemetry.track_error(&some_error, |e| e.context("test", "staging")).await?;
 
// Test custom events
telemetry.track_event("feature_used", |e| e.property("feature", "export")).await?;

2. Verify Privacy Controls

Test that DNT (Do Not Track) is respected:

# Test with DNT enabled
DO_NOT_TRACK=1 cargo run
 
# Verify no events were sent

3. Check HMAC Signatures

Ensure your signature calculation is correct by monitoring for 401 errors:

// If you see 401 Unauthorized, check:
// 1. HMAC secret is correct
// 2. Timestamp is within 5 minutes
// 3. Signature format is correct

4. Monitor Usage

Keep an eye on your staging usage in the dashboard. If you're hitting limits during testing, you may need to:

Batch events more efficiently
Remove debug events
Use feature flags to disable telemetry in dev

5. Clean Promote

Once satisfied with testing:

Review your event data in the dashboard
Confirm events look correct
Click "Promote to Production"
Deploy your app to users

{
  "apps": [
    {
      "id": "app-uuid",
      "name": "My App",
      "environment": "staging",
      "promoted_at": null
    },
    {
      "id": "another-app",
      "name": "Production App",
      "environment": "production",
      "promoted_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Staging Usage API

Check your staging usage programmatically:

GET /api/v1/apps/{app_id}/staging-usage
Authorization: Bearer {token}

Response:

{
  "events_this_month": 847,
  "events_limit": 1000,
  "events_remaining": 153
}

Quick Start Guide - Get started with Telemetry Kit
Self-Hosting - Deploy your own telemetry server
Server API - Complete API reference