Skip to main content

Sending Data to Beakpoint Insights

This guide walks you through configuring your OpenTelemetry exporters to send telemetry data to Beakpoint Insights. By following these best practices, you'll ensure secure and reliable transmission of your traces, metrics, and logs.

Obtaining Your API Key​

Your Beakpoint Insights API key is the primary authentication mechanism for sending telemetry data. Follow these steps to obtain and manage your API key:

  1. Log into your Beakpoint Insights account

  2. Generate a new API key

    • Enter a descriptive name (e.g., "Production Environment", "Development Team") for the key
    • Select an expiration date for the key (optional, but recommended)
    • Click "Create new"

  3. Securely save your API key

    • Copy the generated API key immediately
    • Store it in a secure location (we'll cover best practices below)
    • Note: You will not be able to view the full key again after initial generation

  4. Document key metadata

    • Record the creation date
    • Note which services/environments will use this key
    • Set a reminder for regular key rotation

Endpoint Configuration​

Beakpoint Insights 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 Insights only support traces. We do not support OpenTelemetry metrics, events, or logs.

The main endpoint for sending all traces is:

https://otel.beakpointinsights.com/api/traces

Protocol Support​

Beakpoint Insights 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

  2. HTTP/JSON

    • Human-readable format for debugging
    • Slightly larger payload size
    • Useful for development environments

Example Configurations​

info

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

Configuration:

exporters:
  otlphttp/bkpt:
    traces_endpoint: https://otel.beakpointinsights.com/api/traces
    headers:
      x-bkpt-key: ${BEAKPOINT_API_KEY}
    tls:
      insecure: true
    encoding: json
    protocol: http/protobuf
    compression: none

Environment Variables Setup​

Using environment variables is the recommended approach for managing configuration, especially for sensitive data like API keys. OpenTelemetry supports standardized environment variables that work across different SDKs and languages.

Core Environment Variables​

Set these essential environment variables for basic configuration:

# Service identification with supported cost attribution tags
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"

# Exporter configuration
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://otel.beakpointinsights.com/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 Insights requires two types of tags to provide accurate cost insights:

Cost Calculation Tags enable Beakpoint Insights 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 and API keys is crucial. Follow these security best practices to maintain a secure configuration:

Never hardcode API keys in your source code or configuration files:

# ❌ BAD - Never do this
exporters:
  otlp:
    headers:
      x-bkpt-key: "bkpt_1234567890abcdef"  # NEVER hardcode keys!
# ✅ GOOD - Use environment variables
exporters:
  otlp:
    headers:
      x-bkpt-key: ${BEAKPOINT_API_KEY}

Verifying Data Ingestion​

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

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 Insights Dashboard​

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

3. Troubleshooting Checklist​

If data isn't appearing:

  • API Key is valid and hasn't expired
  • Endpoint URL is correct (including protocol https://)
  • Network connectivity exists (no firewall blocking)
  • Headers are properly formatted with the API key
  • Service name is set (required field)
  • Time synchronization is accurate (within 5 minutes)
  • Data format matches the configured protocol
  • No rate limiting is occurring (check response headers)

4. Success Indicators​

You'll know your configuration is working when:

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