OpenTelemetry - Direct to BYOC Endpoint

Send OpenTelemetry data directly to groundcover's BYOC endpoint

---

Overview

This guide shows how to configure your OpenTelemetry instrumented applications to send telemetry data directly to groundcover's BYOC endpoint, bypassing the in-cluster sensor.

This approach is ideal for:

• Non-Kubernetes workloads (VMs, containers, serverless)

• External services that need to send data without sensor deployment

• Hybrid architectures combining in-cluster and external data sources

FYI: Traces sent to the BYOC endpoint are 100% sampled. All traces will be ingested and stored.

---

Prerequisites

• An active groundcover workspace

• A Third Party Ingestion Key (see Ingestion Keys documentation)

• Your groundcover BYOC endpoint URL

---

Quick Start

HTTP/Protobuf Configuration

For applications using the HTTP protocol with protobuf encoding:

env:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: "https://{BYOC_ENDPOINT}"
  - name: OTEL_EXPORTER_OTLP_PROTOCOL
    value: "http/protobuf"
  - name: OTEL_EXPORTER_OTLP_HEADERS
    value: "token={ingestion-key}"

Note: Do not include the port number (:443) in the endpoint URL. HTTPS defaults to port 443.

Signal-Specific Configuration (HTTP)

If you need to configure traces, logs, and metrics separately:

env:
  # Traces
  - name: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
    value: "https://{BYOC_ENDPOINT}/v1/traces"
  - name: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
    value: "http/protobuf"
  - name: OTEL_EXPORTER_OTLP_TRACES_HEADERS
    value: "token={ingestion-key}"
  
  # Logs
  - name: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
    value: "https://{BYOC_ENDPOINT}/v1/logs"
  - name: OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
    value: "http/protobuf"
  - name: OTEL_EXPORTER_OTLP_LOGS_HEADERS
    value: "token={ingestion-key}"
  
  # Metrics
  - name: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
    value: "https://{BYOC_ENDPOINT}/v1/metrics"
  - name: OTEL_EXPORTER_OTLP_METRICS_PROTOCOL
    value: "http/protobuf"
  - name: OTEL_EXPORTER_OTLP_METRICS_HEADERS
    value: "token={ingestion-key}"

gRPC Configuration

For applications using the gRPC protocol:

env:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: "https://{BYOC_ENDPOINT}"
  - name: OTEL_EXPORTER_OTLP_PROTOCOL
    value: "grpc"
  - name: OTEL_EXPORTER_OTLP_HEADERS
    value: "token={ingestion-key}"

Signal-Specific Configuration (gRPC)

env:
  # Traces
  - name: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
    value: "https://{BYOC_ENDPOINT}"
  - name: OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
    value: "grpc"
  - name: OTEL_EXPORTER_OTLP_TRACES_HEADERS
    value: "token={ingestion-key}"
  
  # Logs
  - name: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
    value: "https://{BYOC_ENDPOINT}"
  - name: OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
    value: "grpc"
  - name: OTEL_EXPORTER_OTLP_LOGS_HEADERS
    value: "token={ingestion-key}"
  
  # Metrics
  - name: OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
    value: "https://{BYOC_ENDPOINT}"
  - name: OTEL_EXPORTER_OTLP_METRICS_PROTOCOL
    value: "grpc"
  - name: OTEL_EXPORTER_OTLP_METRICS_HEADERS
    value: "token={ingestion-key}"

---

Kubernetes Deployment Example

apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-instrumented-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: otel-instrumented-app
  template:
    metadata:
      labels:
        app: otel-instrumented-app
    spec:
      containers:
      - name: app
        image: your-instrumented-app:latest
        env:
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: "https://{BYOC_ENDPOINT}"
        - name: OTEL_EXPORTER_OTLP_PROTOCOL
          value: "http/protobuf"
        - name: OTEL_EXPORTER_OTLP_HEADERS
          valueFrom:
            secretKeyRef:
              name: groundcover-ingestion-key
              key: token
        - name: OTEL_SERVICE_NAME
          value: "my-service"
        - name: OTEL_RESOURCE_ATTRIBUTES
          value: "deployment.environment=production,service.namespace=my-namespace"

Security Best Practice: Always store your Ingestion Key in a Kubernetes Secret, never hardcode it in manifests.

Creating the Secret

kubectl create secret generic groundcover-ingestion-key \
  --from-literal=token="token=your-ingestion-key-here" \
  -n your-namespace

---

OpenTelemetry Collector Configuration

For environments using the OpenTelemetry Collector as a gateway:

exporters:
  otlphttp/groundcover:
    endpoint: https://{BYOC_ENDPOINT}
    headers:
      token: ${GROUNDCOVER_INGESTION_KEY}
    compression: gzip
    timeout: 30s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/groundcover]
    
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/groundcover]
    
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/groundcover]

---

Troubleshooting

Common Issues

403 Forbidden / PERMISSION_DENIED

• Verify your Ingestion Key is valid and not revoked

• Ensure you're using a Third Party type Ingestion Key

• Check that the token header is correctly formatted

Connection Refused / Timeout

• Verify the BYOC endpoint URL

• Check network connectivity and firewall rules

• Ensure port 443 is accessible from your environment

Data Not Appearing

• Check application logs for OTLP exporter errors

• Verify the service name and resource attributes are set

• Allow 1-2 minutes for data to appear in groundcover UI

---

Best Practices

1. Use Resource Attributes: Set meaningful service.name, deployment.environment, and service.namespace to organize your telemetry

2. Secure Key Management: Store Ingestion Keys in secret management systems

---

Comparison: BYOC vs In-Cluster Sensor

Feature	BYOC Endpoint	In-Cluster Sensor
Network Path	Direct to cloud	Local cluster network
Use Case	External services, VMs	Kubernetes workloads
Sampling	100% sampled	Configurable

---

Related Documentation

• OpenTelemetry Sensor Integration

• Ingestion Keys Management

• Traces & Logs

• Metrics