Install OpenTelemetry Collector on VPS — Full Observability Stack
OpenTelemetry (OTel) is a CNCF standard for observability that unifies metrics, distributed traces, and logs under a single protocol — OTLP (OpenTelemetry Protocol). Instead of running a separate agent for every backend, you deploy one OTel Collector, point your apps at it via OTLP, and let the Collector fan out to Prometheus, Jaeger, Loki, or any other backend of your choice.
This guide covers installing OTel Collector on an Ubuntu VPS as a standalone binary (no Kubernetes required), setting up Jaeger for trace visualization, and instrumenting Python and Node.js applications with zero-code-change auto-instrumentation.
OpenTelemetry Architecture
Three building blocks make up an OTel deployment:
- SDK / Auto-instrumentation — runs inside your app (Python, Go, Java, Node.js) and generates spans, metrics, and log records
- OTel Collector — receives telemetry via OTLP gRPC/HTTP, processes and filters it, then exports to one or more backends
- Backends — Prometheus (metrics), Jaeger or Tempo (traces), Loki (logs)
| Signal | Protocol | Default Port | Recommended Backend |
|---|---|---|---|
| Metrics | OTLP gRPC / HTTP | 4317 / 4318 | Prometheus |
| Traces | OTLP gRPC / HTTP | 4317 / 4318 | Jaeger / Tempo |
| Logs | OTLP gRPC / HTTP | 4317 / 4318 | Loki |
Prerequisites
- VPS running Ubuntu 22.04 / 24.04 or Debian 12
- At least 1 GB RAM (2 GB recommended if running Jaeger too)
- Docker + Docker Compose (for backend services)
- Root or sudo access
Install the OTel Collector
We use the otelcol-contrib distribution, which ships with a richer set of receivers, processors, and exporters than the official release.
Download the binary
# Check GitHub releases for the latest version
OTELCOL_VERSION="0.115.0"
ARCH=$(dpkg --print-architecture) # amd64 or arm64
curl -LO "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${OTELCOL_VERSION}/otelcol-contrib_${OTELCOL_VERSION}_linux_${ARCH}.deb"
sudo dpkg -i "otelcol-contrib_${OTELCOL_VERSION}_linux_${ARCH}.deb"
# Verify installation
otelcol-contrib --version
dpkg -i again — it replaces the old binary in place with no manual cleanup needed.Create the config file
OTel Collector YAML config has four sections: receivers, processors, exporters, and service.
sudo mkdir -p /etc/otelcol-contrib
sudo tee /etc/otelcol-contrib/config.yaml <<'EOF'
receivers:
otlp:
protocols:
grpc:
endpoint: "0.0.0.0:4317"
http:
endpoint: "0.0.0.0:4318"
# Collect host metrics from the VPS itself
hostmetrics:
collection_interval: 30s
scrapers:
cpu:
memory:
disk:
load:
network:
filesystem:
processors:
batch:
timeout: 5s
send_batch_size: 1000
resourcedetection:
detectors: [env, system]
system:
hostname_sources: [os]
memory_limiter:
check_interval: 1s
limit_mib: 400
spike_limit_mib: 100
exporters:
# Expose a Prometheus scrape endpoint
prometheus:
endpoint: "0.0.0.0:8889"
namespace: otelcol
# Forward traces to Jaeger
otlp/jaeger:
endpoint: "localhost:14250"
tls:
insecure: true
debug:
verbosity: basic
service:
pipelines:
metrics:
receivers: [otlp, hostmetrics]
processors: [memory_limiter, resourcedetection, batch]
exporters: [prometheus]
traces:
receivers: [otlp]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlp/jaeger, debug]
logs:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [debug]
EOF
Enable and start the service
sudo systemctl enable otelcol-contrib
sudo systemctl start otelcol-contrib
sudo systemctl status otelcol-contrib
Install Jaeger for Distributed Tracing
Jaeger is the trace storage and visualization backend. Run it in all-in-one mode with Docker Compose for a quick start:
mkdir -p ~/jaeger && cat > ~/jaeger/docker-compose.yml <<'EOF'
services:
jaeger:
image: jaegertracing/all-in-one:1.62
ports:
- "16686:16686" # Jaeger UI
- "14250:14250" # gRPC (OTel Collector sends here)
- "14268:14268" # HTTP thrift (legacy)
environment:
COLLECTOR_OTLP_ENABLED: "true"
restart: unless-stopped
EOF
cd ~/jaeger && docker compose up -d
http://your-vps-ip:16686. If you expose it publicly via Nginx or Cloudflare Tunnel, add authentication — Jaeger has no built-in auth in all-in-one mode.Instrument a Python Application
OTel's Python auto-instrumentation works with Flask, FastAPI, Django, SQLAlchemy, and more — no code changes required.
Install packages
pip install opentelemetry-distro opentelemetry-exporter-otlp
# auto-detects the framework and installs the matching instrumentation
opentelemetry-bootstrap -a install
Start the Flask app with OTel
export OTEL_SERVICE_NAME="my-flask-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production"
opentelemetry-instrument python app.py
Instrument a Node.js Application
Use @opentelemetry/sdk-node with auto-instrumentation to cover Express, HTTP outbound calls, and database queries automatically.
Install packages
npm install \
@opentelemetry/sdk-node \
@opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-http \
@opentelemetry/exporter-metrics-otlp-http
Create tracing.js
// tracing.js — load before the app entry point
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const sdk = new NodeSDK({
serviceName: 'my-node-app',
traceExporter: new OTLPTraceExporter({
url: 'http://localhost:4318/v1/traces',
}),
metricReader: new PeriodicExportingMetricReader({
exporter: new OTLPMetricExporter({
url: 'http://localhost:4318/v1/metrics',
}),
exportIntervalMillis: 15000,
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();
Start the app
node --require ./tracing.js server.js
# or in package.json:
# "start": "node --require ./tracing.js server.js"
Connect Prometheus to OTel Collector
The Collector exposes a Prometheus scrape endpoint on port 8889. Add a scrape job to your Prometheus config:
# /etc/prometheus/prometheus.yml — add this scrape job
scrape_configs:
- job_name: 'otelcol'
static_configs:
- targets: ['localhost:8889']
scrape_interval: 30s
# Reload Prometheus to pick up the new config
sudo systemctl reload prometheus
# or: curl -X POST http://localhost:9090/-/reload
Verify OpenTelemetry Collector is Working
# Check service status
sudo systemctl status otelcol-contrib
# Follow logs in real time
sudo journalctl -u otelcol-contrib -f
# Confirm listening ports
ss -tlnp | grep -E '4317|4318|8889'
# Send a test span via OTLP HTTP JSON
curl -X POST http://localhost:4318/v1/traces \
-H "Content-Type: application/json" \
-d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"test-service"}}]},"scopeSpans":[{"spans":[{"traceId":"5B8EFFF798038103D269B633813FC60C","spanId":"EEE19B7EC3C1B174","name":"test-span","startTimeUnixNano":"1700000000000000000","endTimeUnixNano":"1700000001000000000","kind":1,"status":{}}]}]}]}'
# Check metrics exposed for Prometheus
curl -s http://localhost:8889/metrics | grep otelcol | head -20
Memory limit reached, increase limit_mib in the memory_limiter processor, or reduce the collection_interval for the hostmetrics receiver to generate fewer data points.Troubleshooting Common Issues
Error: "bind: address already in use" on port 4317 or 4318
Another process is already holding the port, or otelcol-contrib started more than once.
# Find the offending process
sudo lsof -i :4317
sudo lsof -i :4318
# Kill any stale collector process
sudo pkill -f otelcol-contrib
sudo systemctl start otelcol-contrib
Error: "failed to export traces: context deadline exceeded"
The Collector cannot reach Jaeger. Verify the Jaeger container is running and the port is reachable.
docker ps | grep jaeger
docker logs jaeger --tail 50
# Restart Jaeger if it crashed
cd ~/jaeger && docker compose restart
# Test TCP connectivity from the Collector host
nc -zv localhost 14250
Error: "Dropping data because sending queue is full"
The app is generating more traces than the exporter queue can drain. Tune the exporter's queue settings:
# Add to the otlp/jaeger exporter block in config.yaml
exporters:
otlp/jaeger:
endpoint: "localhost:14250"
tls:
insecure: true
sending_queue:
num_consumers: 4
queue_size: 1000
retry_on_failure:
enabled: true
initial_interval: 5s
max_interval: 30s
sudo systemctl restart otelcol-contrib
Error: "grpc: the client connection is closing" from app
The app is trying to connect to gRPC port 4317, but the Collector is not ready yet or the firewall is blocking the connection.
# Check firewall rules
sudo ufw status | grep -E '4317|4318'
# Bind to localhost only if app and Collector are on the same machine
# In config.yaml:
# endpoint: "127.0.0.1:4317" ← more secure than 0.0.0.0
Metrics not appearing in Prometheus
The Collector is exposing port 8889, but Prometheus hasn't been configured to scrape it yet.
# Check current Prometheus targets
curl -s http://localhost:9090/api/v1/targets | python3 -m json.tool | grep otelcol
# Review prometheus.yml
cat /etc/prometheus/prometheus.yml | grep -A5 otelcol
# Reload after editing
sudo systemctl reload prometheus
Frequently Asked Questions
How is OTel Collector different from Prometheus Node Exporter?
Node Exporter collects host-level Linux metrics (CPU, memory, disk) and exposes them for Prometheus to scrape. OTel Collector is a universal telemetry pipeline: it receives metrics, traces, and logs from your applications via OTLP and routes them to multiple backends simultaneously. In practice, most teams run both — Node Exporter for host metrics and OTel Collector for application telemetry.
Do I need to change a lot of code to instrument my app?
With auto-instrumentation (Python's opentelemetry-instrument wrapper or Node.js's --require ./tracing.js flag) you change zero application code. Frameworks like Flask, FastAPI, and Express are instrumented automatically, including HTTP calls, database queries, and Redis. You only need to add code if you want custom spans or attributes beyond what the auto-instrumentation captures.
How much memory does OTel Collector use?
On a 1 vCPU / 1 GB VPS, the Collector typically uses 50–150 MB of RAM and less than 1% CPU under normal load. For high-traffic services that generate many spans, increase the RAM budget in memory_limiter and consider enabling the tail_sampling processor to retain only traces that meet criteria such as error status or long latency.