This guide walks you through configuring your existing OpenTelemetry instrumentation to send data to a self-hosted SigNoz instance. The process involves updating your export configuration - no changes to your application code are required.

Prerequisites

• Applications instrumented with OpenTelemetry SDKs or OpenTelemetry Collectors
• OTLP exporters configured (HTTP or gRPC)
• Docker or Kubernetes environment for SigNoz installation

Step 1: Install Self-Hosted SigNoz

Before configuring OpenTelemetry, you need a running SigNoz instance.

Follow the installation guide: Install Self-Hosted SigNoz

The guide covers multiple deployment options including Docker, Kubernetes, and cloud platforms.

Step 2: Identify Your SigNoz Endpoints

Locate your SigNoz OpenTelemetry Collector endpoints. These are typically:

• gRPC (recommended): http://<your-signoz-host>:4317
• HTTP: http://<your-signoz-host>:4318

Examples:

• Local installation: http://localhost:4317
• Remote server: http://signoz.yourcompany.com:4317
• Docker network: http://signoz-container:4317

Step 3: Update OpenTelemetry Configuration

Now you need to reconfigure your OpenTelemetry exporters to send data to your SigNoz instance instead of your previous backend. You can do this through environment variables (recommended) or by updating your application code directly.

Environment Variables (Recommended)

Set these environment variables for your application:

# Replace with your SigNoz instance endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT="http://your-signoz-host:4317"

# Enable compression for better performance
export OTEL_EXPORTER_OTLP_COMPRESSION="gzip"

# Optional: Increase timeout for large payloads
export OTEL_EXPORTER_OTLP_TIMEOUT="30000"

# For insecure connections (development only)
export OTEL_EXPORTER_OTLP_INSECURE="true"

Programmatic Configuration Examples

If you prefer to configure exporters directly in code, here are examples for common languages:

Node.js

const { OTLPTraceExporter } = require('@opentelemetry/exporter-otlp-grpc');

const exporter = new OTLPTraceExporter({
  url: 'http://your-signoz-host:4317',
  compression: 'gzip'
});

Python

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="http://your-signoz-host:4317",
    insecure=True,  # For HTTP endpoints
    compression="gzip"
)

Go

exporter, err := otlptracegrpc.New(ctx,
    otlptracegrpc.WithEndpoint("http://your-signoz-host:4317"),
    otlptracegrpc.WithInsecure(), // For HTTP endpoints
)

Java

OtlpGrpcSpanExporter exporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint("http://your-signoz-host:4317")
    .setCompression("gzip")
    .build();

.NET

using var tracerProvider = TracerProviderBuilder.Create()
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri("http://your-signoz-host:4317");
        options.Protocol = OtlpExportProtocol.Grpc;
    })
    .Build();

PHP

use OpenTelemetry\Contrib\Otlp\SpanExporter;

$exporter = new SpanExporter('http://your-signoz-host:4317');

Ruby

require 'opentelemetry/exporter/otlp'

exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(
  endpoint: 'http://your-signoz-host:4317'
)

Step 4: Update OpenTelemetry Collector Configuration

If you're using an OpenTelemetry Collector in your infrastructure to aggregate telemetry data before sending it to backends, you'll need to update its configuration to point to your SigNoz instance. This is common in production setups where the collector handles data processing, filtering, and routing.

Update your collector's configuration file:

exporters:
  otlp:
    endpoint: "your-signoz-host:4317"
    tls:
      insecure: true  # Set to false if using HTTPS

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

After updating the configuration, restart your OpenTelemetry Collector to apply the changes.

Step 5: Configure TLS/SSL (Production Recommended)

For production environments, secure your SigNoz installation with HTTPS. The approach depends on your deployment method:

• Kubernetes: Follow the official TLS setup guide using Ingress NGINX and Cert Manager
• Docker/VM: Configure a reverse proxy (nginx, Traefik, HAProxy) to handle SSL termination

Once HTTPS is configured, update your OpenTelemetry endpoint:

# Use HTTPS endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT="https://signoz.yourcompany.com:443"

Step 6: Test and Validate

Now it's time to verify that your OpenTelemetry data is successfully flowing to your SigNoz instance.

1. Restart Your Applications

After updating the configuration, restart your instrumented applications to apply the new settings.

2. Generate Test Data

Use your application to generate some activity - trigger API calls, database queries, or other instrumented operations. Wait 1-2 minutes for data to appear.

3. Verify Data in SigNoz

1. Access SigNoz Dashboard: Navigate to http://your-signoz-host:3301
2. Check Services: Go to the Services tab and verify your applications appear
3. Validate Traces: Click on a service to see traces and spans
4. Check Metrics: Verify application and infrastructure metrics are flowing

If data doesn't appear, check your application logs for OpenTelemetry export errors and ensure SigNoz is accessible from your application network.

Troubleshooting

If data doesn't appear in SigNoz:

1. Check connectivity: Ensure your application can reach the SigNoz OTLP endpoint (port 4317 for gRPC or 4318 for HTTP)
2. Verify configuration: Double-check endpoint URLs and ensure they match your SigNoz installation
3. Review logs: Check both application and SigNoz container logs for errors
4. Network issues: Verify firewall rules and DNS resolution

For detailed troubleshooting, see the SigNoz documentation.

Next Steps

Once your migration is complete:

• Set up alerts for key metrics
• Create custom dashboards
• Follow production best practices