Ingestion Overview for Self-Hosted SigNoz

SigNoz's self-hosted/community edition does not use ingestion keys, requiring users to control their own OpenTelemetry pipeline and endpoints. The platform accepts OTLP data via gRPC on port 4317 or HTTP on port 4318, with endpoints varying by deployment environment such as Docker, Kubernetes, or virtual machines. Users must configure their language SDKs or OpenTelemetry Collectors to export data to the appropriate SigNoz OTLP endpoint based on their infrastructure setup.

Self-hosted/community edition of SigNoz does not use ingestion keys. You control your own OpenTelemetry pipeline and endpoints. Overview SigNoz is OpenTelemetry-native and works with OpenTelemetry Protocol OTLP https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md . Send OTLP data directly to the SigNoz OpenTelemetry Collector installed with SigNoz, or run your own collector as an agent and forward to SigNoz. - OTLP/gRPC: default port 4317 - OTLP/HTTP: default port 4318 Prerequisites - A running self-hosted SigNoz instance. See: Install Self-Host SigNoz https://signoz.io/docs/install/self-host/ - Network access from your applications/collectors to the SigNoz OTLP ports 4317 for gRPC, 4318 for HTTP Get Started - Identify your SigNoz OTLP endpoint host and ports . See the Address Grid below for common setups. - Configure your language SDKs or your own OpenTelemetry Collector to export to that endpoint. Endpoints Unless you’ve enabled TLS, use http:// on port 4317 gRPC or 4318 HTTP . For gRPC without TLS, set OTEL EXPORTER OTLP PROTOCOL=grpc and an http:// endpoint. Some SDKs require insecure: true in their exporter config as well. | Protocol | Endpoint | Notes | |---|---|---| | OTLP/gRPC | http://<signoz-host :4317 | No path suffix | | OTLP/HTTP | http://<signoz-host :4318 | SDK adds /v1/{traces|metrics|logs} | 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 Use the grid below to pick the right OTLP endpoint for your deployment. | Where SigNoz is installed? | ||||| |---|---|---|---|---|---| | VM Docker - Same Machine | VM Docker - Different Machine | K8s Same Cluster | K8s Different Cluster | || | Where your application is running? | VM native/binary | localhost:4317 | <otelcollector-IP :4317 | <k8s-node-IP :<otelcollector-node-port , <k8s-loadbalancer-IP :4317 | <k8s-node-IP :<otelcollector-node-port , <k8s-loadbalancer-IP :4317 | | VM Docker | 172.17.0.1:4317, otel-collector:4317 shared network | <otelcollector-IP :4317 | <k8s-node-IP :<otelcollector-node-port , <k8s-loadbalancer-IP :4317 | <k8s-node-IP :<otelcollector-node-port , <k8s-loadbalancer-IP :4317 | | | Kubernetes | <otelcollector-IP :4317 | <otelcollector-IP :4317 | <release-name -signoz-otel-collector.<namespace .svc.cluster.local:4317 | <k8s-node-IP :<otelcollector-node-port , <k8s-loadbalancer-IP :4317 | - For the <otelcollector-IP , use a private IP address if the VM is in the same private network. - Replace <namespace with the SigNoz namespace and <release-name with the SigNoz Helm release name. - If your application and SigNoz run in different Kubernetes clusters, expose the OTLP service. Set the service type to either NodePort or LoadBalancer . - The grid uses OTLP/gRPC 4317 . If you prefer OTLP/HTTP, use port 4318 accordingly. Language SDK Configuration Most language SDKs honor the signal-agnostic environment variable OTEL EXPORTER OTLP ENDPOINT . To configure with the signal-agnostic variable, set: gRPC OTEL EXPORTER OTLP PROTOCOL=grpc OTEL EXPORTER OTLP ENDPOINT=http://<signoz-host :4317 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 in milliseconds 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 https://signoz.io/docs/instrumentation/ . OpenTelemetry Collector Configuration To forward from your own collector to SigNoz, configure the OTLP exporter: 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 For otlp gRPC , use the tls.insecure: true option only when sending to a plain HTTP endpoint no TLS . For otlphttp , you don't need a TLS block when using http:// . If you switch to https:// , you can add a tls section e.g., to trust custom CAs and set insecure: false . 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 https://signoz.io/docs/opentelemetry-collection-agents/opentelemetry-collector/configuration/ Authentication Self-hosted SigNoz requires no ingestion keys. For authentication, place SigNoz behind a reverse proxy nginx/Traefik/HAProxy or Kubernetes ingress and enforce TLS and auth there. Important Considerations Payload Size The OTLP/gRPC receiver enforces a configurable max receive message size. If you hit ResourceExhausted errors on large payloads, increase max recv msg size mib under the grpc receiver in your collector config: receivers: otlp: protocols: grpc: max recv msg size mib: 16 OTLP/HTTP payload limits are controlled by the HTTP server layer and configured separately. CORS CORS is off by default for all origins. The default Docker config explicitly allows only http://localhost:8080 and http://localhost:8081 — every other origin, including other localhost ports, is blocked by browsers. To allow browser telemetry from your app's origin, add it to allowed origins in your OTLP/HTTP receiver config: receivers: otlp: protocols: http: cors: allowed origins: - https://your-app.example.com See CORS in OTLP HTTP Receiver https://signoz.io/docs/userguide/otlp-http-enable-cors/ for Docker and Kubernetes instructions. Compression Enable gzip compression to reduce bandwidth. SDKs: set OTEL EXPORTER OTLP COMPRESSION=gzip . Collectors: set compression: gzip on each exporter. Timeouts For SDKs, set OTEL EXPORTER OTLP TIMEOUT in milliseconds e.g., 30000 for 30s . For collectors, tune exporters - otlp - timeout to match your payload size and network. Retries and Queueing For Collector deployments, configure retry on failure and sending queue to reduce data loss on transient failures: 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 SDKs expose signal-specific env vars for batch export tuning: OTEL BSP — batch span processor traces OTEL METRIC EXPORT — metric export interval and timeout OTEL BLRP — batch log record processor logs See the OpenTelemetry SDK environment variables spec https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/ for all options. Protocol Choice OTLP/gRPC port 4317 offers better performance and backpressure handling for server-side telemetry. OTLP/HTTP port 4318 is simpler to configure, easier to debug, and required for browser-based telemetry where gRPC is not supported. TLS in Production Secure your endpoint with TLS via ingress or a reverse proxy. After enabling TLS, use https:// endpoints and ensure your SDKs and collectors trust the certificate. See: Secure SigNoz in Kubernetes https://signoz.io/docs/tutorial/setting-up-tls-for-signoz/ . Troubleshooting If data doesn’t appear in SigNoz: - Verify connectivity to 4317 gRPC or 4318 HTTP - Check OTLP endpoints and protocol in your SDK/collector config - Check application and collector logs for export errors - Verify network/firewall/DNS reachability - See the Address Grid above to confirm the correct endpoint and port. Migrating from an existing OpenTelemetry setup? See: Migrate from existing OpenTelemetry to Self-Hosted SigNoz https://signoz.io/docs/migration/migrate-from-opentelemetry-to-signoz/ .