Real‑Time Telemetry Log Streaming (Graylog & SigNoz)

This guide shows how to stream proxy access logs to Graylog or SigNoz in real time, so you can monitor multiple proxy devices from one place.

• Supported providers: Graylog (GELF UDP) and SigNoz (OTLP/HTTP).
• Where to configure: XProxy → General Settings > Telemetry Logs.

Centralized log management — Multiple XProxy devices

Stream logs from many XProxy servers/devices into a single Graylog or SigNoz workspace to gain holistic visibility and simpler querying across regions, clusters, or projects.

• Unified monitoring: watch access and health in real time across all nodes.
• Easy querying: filter by device, service, region, action, or error code.
• Faster troubleshooting: quickly isolate errors, spikes, or abnormal behaviors.

Recommended labeling

• Use Host Identifier for per-server names (e.g., sg-core-01, us-east-02).
• Use Service Name to group by region or business unit (e.g., xproxy-region-a, xproxy-affiliate).
• Every log carries these labels, making it easy to build dashboards and filters.

Common use cases

• Unique client IP counting to estimate real traffic and spot unfamiliar sources.
• Error rate tracking by filtering error_code != 00000.
• Top destinations & bandwidth via destination_host, received_bytes, and sent_bytes.
• Per-device/port monitoring using modem_position, proxy_port, proxy_service.
• Anomaly detection for sudden traffic spikes or elevated error codes.

Query examples

Graylog

• By service/cluster: service_name:xproxy-region-a
• Only errors: error_code:!00000
• By action: action:CONNECT or action:ACCESS
• By device/slot: modem_position:3
• Dashboards:
  • Unique IP: Unique Count on client_ip, group by service_name or modem_position.
  • Top destination: Count grouped by destination_host.
  • Bandwidth: Sum of received_bytes and sent_bytes over time, grouped by service_name.

SigNoz

• By service name: service.name = "xproxy-region-a"
• Only errors: attributes.error_code != "00000" or severity_text = "ERROR"
• By action: attributes.action = "CONNECT"
• By device/slot: attributes.modem_position = 3
• Charts:
  • Unique IP: Unique Count on attributes.client_ip, group by service.name or attributes.modem_position.
  • Top destination: Count grouped by attributes.destination_host.
  • Bandwidth: Sum of attributes.received_bytes and attributes.sent_bytes with time buckets.
  • Error rate: Ratio of attributes.error_code != "00000" over total requests.

Operational tips for many devices

• Consistent naming: standardize Host Identifier and Service Name by region/group.
• Environment separation: use prefixes like prod-/stg- in Service Name.
• Retention planning: set index rotation/retention in Graylog; monitor usage/retention in SigNoz Cloud.
• Health alerts: alert when a node stops sending logs for N minutes; re-run Test Connection after adding new nodes.

Option A — Graylog

Requirements: Ubuntu Server (20.04 or 22.04)

VPS sizing (recommended): at least 2 GB RAM, best 4 GB RAM for smoother Elasticsearch/Graylog performance. A budget option is Hostinger VPS with 4 GB RAM at around $5.5/month.

Install Graylog (one‑line script):

curl x-proxy.io/graylog | bash

After installation, open Graylog and create a UDP input:

1. Go to System > Inputs.
2. Choose GELF UDP and click Launch new input.
3. Set Bind address to 0.0.0.0 and Port to 12201 (default).
4. Click Save.

Now configure XProxy:

1. Open General Settings > Telemetry Logs.
2. Toggle Enable Telemetry ON.
3. Set Provider to Graylog.
4. Enter Graylog Server (IP:Port), e.g. YOUR_GRAYLOG_IP:12201.
5. Optionally set Host Identifier (your server name) and Service Name (e.g., xproxy-region-a). All logs will carry this prefix.
6. Confirm Log Path (default /etc/xproxy/logs).
7. Click Save, then Test Connection.

Check data in Graylog: use the search box with queries like service_name:xproxy-logs or action:CONNECT.

Option B — SigNoz

You can use SigNoz Cloud (no server needed) or install the community edition.

Requirements: Ubuntu Server (20.04, 22.04, or 24.04)

Install SigNoz (Community):

curl x-proxy.io/signoz | bash

Skip installation if you use SigNoz Cloud. Obtain your OTLP/HTTP endpoint and Ingestion Key from your workspace settings.

Configure XProxy for SigNoz:

1. Open General Settings > Telemetry Logs.
2. Toggle Enable Telemetry ON and select SigNoz as Provider.
3. Fill OTLP/HTTP Endpoint, e.g. https://ingest.us.signoz.cloud:4318.
4. Paste your Ingestion Key (SigNoz Cloud) or leave blank for local/community setups if not required.
5. Set Service Name (e.g., xproxy-region-a) and confirm Log Path. All logs will carry this prefix.
6. Click Save, then Test Connection.

View logs in SigNoz: go to Logs > Explorer. Use the exact Service Name you configured in XProxy (the "xproxy-logs" shown here is default/demo). For example: service.name = "xproxy-region-a". You can also search without any filter to see all logs first, then refine (e.g., attributes.action = "CONNECT").

What each log field means

XProxy parses every access line and sends structured attributes. You can search and build dashboards on these fields.

• log_date — Date of the log (DD/MM).
• log_time — Time of the log (HH:MM:SS).
• proxy_service — Service group name (e.g. MAIN).
• modem_position — Device/slot index serving the request.
• proxy_protocol — HTTP or SOCKS5 (may be empty if not detected).
• proxy_port — Proxy listening port on XProxy (e.g. 6001).
• proxy_user — Username used to authenticate (empty when using IP whitelist).
• client_ip — IP of the client using the proxy.
• client_port — Source port of the client connection.
• destination_host — Target host requested via proxy.
• destination_port — Target port (from CONNECT/ACCESS info).
• action — Operation type, e.g. CONNECT or ACCESS.
• error_code — 00000 means success; non‑zero indicates an error condition.
• received_bytes — Bytes from destination to client.
• sent_bytes — Bytes from client to destination.

Additional provider/resource fields may appear (e.g., service.name, severity_text, telemetry.sdk.*) when using SigNoz/OpenTelemetry.

Verify everything works

• Graylog: Search service_name:xproxy-logs and check message fields on the right panel.
• SigNoz: In Logs Explorer, filter by your exact configured service name, e.g. service.name = "xproxy-region-a" (the "xproxy-logs" value is default/demo). Or clear filters to see all logs and confirm ingestion; open any row to see attributes.

Troubleshooting

• No data: Ensure telemetry is enabled and you clicked Save. Generate traffic via any proxy port.
• Graylog: Confirm the GELF UDP input is running on port 12201 and firewall allows UDP 12201.
• SigNoz: Endpoint must include port 4318 and be reachable via HTTPS. Verify the ingestion key and workspace region.

Log error codes reference

XProxy emits a five‑digit error_code in logs (e.g., 00000, 00004). Leading zeros are intentional for consistent sorting and filtering.

• 00000 — Operation successfully completed (connection closed by one of peers).
• 00001–00009 — Authentication errors (ACL/username/password related).
• 00010 — Traffic limit exceeded.
• 00011–00019 — Connection errors (socket/bind/connect, etc.).
• 00020–00029 — Common internal errors (e.g., memory allocation failed).
• 00030–00039 — HTTP CONNECT proxy redirection errors.
• 00050–00069 — SOCKS5 proxy redirection errors.
• 00090–00099 — Established connection errors/timeouts/network issues.
• 00100 — Host not found.
• 00200–00299 — UDP portmapper specific errors.
• 00300–00399 — TCP portmapper specific errors.
• 00400–00499 — SOCKS proxy specific errors.
• 00500–00599 — HTTP proxy specific errors.

Q/A — Frequently asked