Ingestion Overview

Overview

SigNoz is OpenTelemetry-native and works with OpenTelemetry Protocol (OTLP). For self-hosted deployments, you typically send OTLP data directly to the SigNoz OpenTelemetry Collector that is installed with SigNoz, or to a collector you manage and then forward it to SigNoz.

• OTLP/gRPC: default port 4317
• OTLP/HTTP: default port 4318

Prerequisites

• A running self-hosted SigNoz instance. See: Install Self-Host SigNoz
• Network access from your applications/collectors to the SigNoz OTLP ports (4317 for gRPC, 4318 for HTTP)

Get Started

1. Identify your SigNoz OTLP endpoint (host and ports). See the Address Grid below for common setups.
2. Configure your language SDKs or your own OpenTelemetry Collector to export to that endpoint.

Endpoints

Use the appropriate protocol and port based on your setup. Unless you’ve enabled TLS/ingress, use non‑TLS endpoints (http://) on 4317 (gRPC) or 4318 (HTTP). For gRPC, also set OTEL_EXPORTER_OTLP_INSECURE=true (or the equivalent client option) as some SDKs require it explicitly.

http://<signoz-host>:4317

http://<signoz-host>:4318

Examples:

• Local Docker/Binary: http://localhost:4317 or http://localhost:4318
• Docker network: http://otel-collector:4317
• Kubernetes (same cluster): <release-name>-signoz-otel-collector.<namespace>.svc.cluster.local:4317
• Exposed from Kubernetes: <node-ip>:<node-port> or <loadbalancer-ip>:4317

Collector Address Grid

You might have specific setups for your application and your SigNoz cluster. It’s not always obvious which address to use to send data. Use the grid below to quickly pick the right OTLP endpoint.

Language SDK Configuration

Most language SDKs honor the signal-agnostic environment variable OTEL_EXPORTER_OTLP_ENDPOINT.

If you are using the signal-agnostic variable, you can set:

# gRPC (recommended)
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://<signoz-host>:4317

# OR HTTP/protobuf
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://<signoz-host>:4318

# Common tuning
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_TIMEOUT=30000   # 30s
OTEL_EXPORTER_OTLP_INSECURE=true   # when not using TLS

When using OTLP/HTTP and the signal-agnostic endpoint, SDKs automatically append the correct path (for example, /v1/traces, /v1/metrics, /v1/logs). For language-specific instructions, see the instrumentation docs.

OpenTelemetry Collector Configuration

If you run your own collector (agent or gateway) and want to forward to SigNoz, set the OTLP exporter to point at your SigNoz collector:

exporters:
  otlp: # gRPC
    endpoint: '<signoz-host>:4317'
    tls:
      insecure: true # set to false when using TLS/HTTPS

  # or use HTTP
  otlphttp:
    endpoint: 'http://<signoz-host>:4318'

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

This configures an OpenTelemetry Collector to forward telemetry to your SigNoz instance. Replace the placeholders:

• <signoz-host>: Hostname or IP of your SigNoz OTLP endpoint
• insecure: true: Use only when not using TLS. Set to false when using HTTPS

Read more: OpenTelemetry Collector Configuration

Authentication

No ingestion keys are required for self-hosted SigNoz. If you need authentication, place SigNoz behind a reverse proxy (nginx/Traefik/HAProxy) or Kubernetes ingress and enforce TLS and auth there.

Best Practices

• Prefer OTLP/gRPC where possible (better performance, backpressure) and OTLP/HTTP for browser-based telemetry.
• Enable compression to reduce bandwidth and improve reliability. SDKs: OTEL_EXPORTER_OTLP_COMPRESSION=gzip. Collectors: compression: gzip on exporters.
• Configure retries and queueing (Collector) for resilience. Use retry_on_failure and sending_queue. Refer to the recommended defaults below.
• Tune timeouts. For SDKs, use OTEL_EXPORTER_OTLP_TIMEOUT. For collectors, adjust exporters -> otlp -> timeout based on payload size and network.
• Watch payload size limits. gRPC receivers/exporters enforce limits (e.g., max_recv_msg_size_mib is set to 16MB). Increase if needed. See examples in Linux install and Azure Container Apps.
• For frontend/browser telemetry, explicitly enable CORS on the OTLP/HTTP receiver. See CORS in OTLP HTTP Receiver.
• Use TLS in production via ingress or reverse proxy; update SDKs and collectors to trust the certificates.

Recommended exporter defaults:

exporters:
  otlp:
    timeout: 5s
    compression: gzip
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
    sending_queue:
      enabled: true
      num_consumers: 10
      queue_size: 1000

Troubleshooting

If data doesn’t appear in SigNoz:

• Verify connectivity to 4317 (gRPC) or 4318 (HTTP)
• Double-check OTLP endpoints and protocol in your SDK/collector
• Review application and collector logs for export errors
• Confirm network/firewall/DNS reachability
• Refer to the Address Grid above to verify the correct endpoint and port.

If you are migrating an existing OpenTelemetry setup to SigNoz, see: Migrate from existing OpenTelemetry to Self-Hosted SigNoz.