Skip to main content

Sending Data to Beakpoint

This guide shows you how to configure OpenTelemetry exporters to send traces to Beakpoint securely and reliably.

Obtaining Your API Key​

Your Beakpoint API key authenticates all telemetry data sent from your exporters.

  1. Log into Beakpoint

  2. Create a new API key

    • Choose a descriptive name (e.g., "Production", "Staging", "Dev Team")
    • Optionally set an expiration date (recommended for security)
    • Click "Create new"

  3. Save the key securely

    • Copy the key immediately — it won't be visible again
    • Store it in your secrets management system (covered below)

  4. Track key metadata

    • Document which services use each key
    • Set a calendar reminder to rotate keys regularly (every 90 days recommended)

Endpoint Configuration​

Beakpoint provides OTLP-compatible endpoints for receiving telemetry data. Configure your exporters to use the appropriate endpoint based on your needs.

Primary Endpoint​

info

Remember that Beakpoint only supports traces. We do not support OpenTelemetry metrics, events, or logs.

The main endpoint for sending all traces is:

https://otel.beakpoint.io/api/traces

Protocol Support​

Beakpoint supports the following OTLP protocols:

  1. HTTP/Protobuf (Recommended)

    • Best balance of performance and compatibility
    • Supports both HTTP/1.1 and HTTP/2
    • Binary encoding for efficient transmission
    • Use protocol: http/protobuf with encoding: protobuf

  2. HTTP/JSON

    • Human-readable format for debugging
    • Slightly larger payload size
    • Useful for development environments
    • Use protocol: http/protobuf with encoding: json

Example Configurations​

info

The configuration shown below is an example of how you can configure your otel-collector to forward traces to Beakpoint. Alternatively, you can provide the same settings directly in your code.

Configuration:

exporters:
  otlphttp/bkpt:
    traces_endpoint: https://otel.beakpoint.io/api/traces
    headers:
      x-bkpt-key: ${BEAKPOINT_API_KEY}
    encoding: protobuf
    protocol: http/protobuf
    compression: none

Environment Variables Setup​

Environment variables are the recommended way to configure your exporters across all SDKs and languages. OpenTelemetry supports standardized environment variables for consistent setup.

Core Environment Variables​

Set these variables before starting your application:

# Service identification
export OTEL_SERVICE_NAME="your-service-name"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production,service.namespace=backend,cloud.provider=aws,cloud.region=us-east-1"

# Beakpoint exporter configuration
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://otel.beakpoint.io/api/traces"
export OTEL_EXPORTER_OTLP_HEADERS="x-bkpt-key=${BEAKPOINT_API_KEY}"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

Cost Calculation and Attribution Tags​

Beakpoint requires two types of tags to provide accurate cost insights:

Cost Calculation Tags enable Beakpoint to determine the actual infrastructure costs associated with each trace. Since different computing resources (Lambda functions, EC2 instances, RDS databases) have different cost models, these tags provide the specific metadata needed to calculate costs accurately for each cloud service.

Cost Attribution Tags unlock the true power of cost analysis by helping you understand what drives your infrastructure spend. These tags let you slice and dice your costs by service, user, environment, organization, or any other business dimension that matters to your team.

Together, these tags transform raw telemetry data into actionable cost insights, allowing you to identify which parts of your application are most expensive to run and optimize accordingly.

For detailed implementation:

Securely Managing Your API Key​

Protecting your telemetry pipeline is crucial. Follow these security best practices:

Never hardcode API keys in source code or configuration files:

# ❌ BAD - Never do this
exporters:
  otlp:
    headers:
      x-bkpt-key: "bkpt_1234567890abcdef"  # NEVER hardcode keys!

Always use environment variables to inject keys at runtime:

# ✅ GOOD
exporters:
  otlp:
    headers:
      x-bkpt-key: ${BEAKPOINT_API_KEY}

Store API keys in your secrets management system (e.g., AWS Secrets Manager, HashiCorp Vault, GitHub Secrets) and inject them as environment variables at deployment time.

Verifying Data Ingestion​

After configuring your exporter, verify that data is successfully reaching Beakpoint:

1. Enable Debug Logging​

Temporarily enable verbose logging to troubleshoot issues:

# For OpenTelemetry Collector
export OTEL_LOG_LEVEL=debug

# For .NET applications
export OTEL_DOTNET_AUTO_LOG_LEVEL=debug

# For Node.js applications
export OTEL_LOG_LEVEL=debug

2. Check Beakpoint Dashboard​

  1. Log in to Beakpoint
  2. On your dashboard, check to see what time your most recent traces were received.

3. Troubleshooting Checklist​

If data isn't appearing after 5–10 minutes, work through these checks:

  • API Key is valid — Generate a new key if in doubt; check the dashboard for key status
  • Endpoint URL is correct — Verify it's https://otel.beakpoint.io/api/traces (not http://)
  • Network connectivity exists — Run curl -v https://otel.beakpoint.io/api/traces to confirm DNS and firewall access
  • Headers are properly formatted — Ensure x-bkpt-key matches your actual API key exactly
  • Service name is set — Check that OTEL_SERVICE_NAME or span resource attributes are populated
  • Time synchronization is accurate — Ensure server time is within 5 minutes of NTP (run date to verify)
  • Encoding and protocol match — If using protobuf protocol, use protobuf encoding; if HTTP/JSON, use json encoding
  • No rate limiting is occurring — Check exporter logs for 429 status codes; contact support if rate limits are hit

4. Success Indicators​

You'll know your configuration is working when:

  • ✅ Traces appear in Beakpoint within 30 minutes
  • ✅ All service names are correctly identified
  • ✅ Span attributes include cost calculation tags