Skip to content
Layer Nine Docs

Zabbix

This guide configures Zabbix 6.4+ to stream metrics and events to Layer 9 using the native Streaming Connector feature.

Prerequisites

Section titled “Prerequisites”
  • Zabbix Server version 6.4 or higher
  • Administrator access to Zabbix Web UI
  • Connector workers must be enabled in Zabbix server configuration
    • Why: Connector workers are required for the streaming connector feature to function
    • How to enable: Set StartConnectors=1 in /etc/zabbix/zabbix_server.conf
    • Verify: After restarting Zabbix server, check logs for “connector worker” processes started
    • Alternative: Some Zabbix installations enable this by default; verify in server logs if connector workers are running
  • Zabbix must have hosts with items collecting data (the connector streams existing metrics)
    • Check: Monitoring → Latest data - you should see metrics with recent timestamps
    • If no data exists, configure hosts and items first before setting up the connector
  • Outbound internet access to the metrics endpoint
    • Firewall allows egress to TCP 443
    • Router/NAT supports outgoing HTTPS

Step 1: Coordinate with Layer 9 Team

Section titled “Step 1: Coordinate with Layer 9 Team”

Contact the Layer 9 team to obtain your organization-specific connection details:

  • Metrics endpoint URL: https://<name>.zabbix.layer9.com/v1/history
  • Events endpoint URL: https://<name>.zabbix.layer9.com/v1/events
  • Bearer token

Step 2: Verify You Have Metrics

Section titled “Step 2: Verify You Have Metrics”

Before configuring the connector, verify that Zabbix is collecting metrics:

  1. Navigate to Monitoring → Latest data in the Zabbix web interface
  2. Select a host from the dropdown
  3. You should see items with recent values and timestamps

Important: The connector only streams metrics that Zabbix is already collecting. If you see no data in “Latest data”, you need to configure hosts and items first.

Step 3: Configure Connectors

Section titled “Step 3: Configure Connectors”

Navigate to Administration > General > Connectors in the Zabbix web interface.

Item Values Connector

Section titled “Item Values Connector”

Create a connector for streaming item values (metrics):

Setting Value
Name Layer9 Metrics Export
Data type Item values
URL https://<name>.zabbix.layer9.com/v1/history
HTTP authentication Bearer
Bearer token Your bearer token
Max records per message 10000
Concurrent sessions 4
Attempts 3
Attempt interval 10s
Timeout 30s

Tag filtering (recommended):

Layer 9 templates use export: no tag to exclude items from streaming (e.g., ICMP ping).

To enable filtering, scroll to Tag filter section and add:

Tag filter calculation Tag Operator Value
And/Or export Does not equal no

Events Connector

Section titled “Events Connector”

Create a connector for streaming events:

Setting Value
Name Layer9 Events Export
Data type Events
URL https://<name>.zabbix.layer9.com/v1/events
HTTP authentication Bearer
Bearer token Your bearer token
Max records per message 10000
Concurrent sessions 4
Attempts 3
Attempt interval 10s
Timeout 30s
Section titled “Recommended Settings Explained”
Setting Recommended Why
Max records per message 10000 Smaller batches complete within timeout, reducing connection drops
Concurrent sessions 4 Parallel requests improve throughput without overwhelming Layer 9
Attempts 3 Automatic retries on transient failures prevent data loss
Attempt interval 10s Allows recovery time between retry attempts
Timeout 30s Sufficient for 10k records; increase if using larger batches

Supported Data Types

Section titled “Supported Data Types”

All Zabbix value types are forwarded to Layer 9:

Type Description Forwarded
0 Numeric (float) Yes
1 Character Yes
2 Log Yes
3 Numeric (unsigned) Yes
4 Text Yes
5 Binary Yes

The value type is preserved in the metric metadata for downstream processing.

Troubleshooting

Section titled “Troubleshooting”

No Metrics Flowing

Section titled “No Metrics Flowing”

If the connector is configured but no metrics are being received:

  1. Verify Zabbix has data:

    • Go to Monitoring → Latest data
    • Select a host
    • Confirm you see items with recent values
    • If empty, configure hosts and items first

  2. Check connector status:

    • Go to Administration → General → Connectors
    • Verify connector shows green/enabled status
    • Check for any error messages

  3. Verify network connectivity:

    • Ensure outbound HTTPS (TCP 443) is allowed
    • Test connectivity: curl https://<name>.zabbix.layer9.com/healthz

Connector Shows Errors

Section titled “Connector Shows Errors”
  • Verify the URL includes the full path (/v1/history or /v1/events)
  • Verify the bearer token matches what was provided by Layer 9
  • Check Zabbix server logs for connector-related errors

Connection Timeouts or Dropped Connections

Section titled “Connection Timeouts or Dropped Connections”

If you see timeout errors or partial data uploads:

  1. Reduce batch size: Set “Max records per message” to 10000 or lower
  2. Increase timeout: If batches must be larger, increase “Timeout” accordingly

Connector Workers Not Running

Section titled “Connector Workers Not Running”

If you see errors like “connectors cannot be used without connector workers”:

  1. Enable connector workers in Zabbix server configuration:

    • Edit /etc/zabbix/zabbix_server.conf
    • Add or set: StartConnectors=1
    • Restart Zabbix server: systemctl restart zabbix-server (or your service manager)

  2. Verify connector workers started:

    • Check Zabbix server logs for: “connector worker” processes started
    • Should see messages like: “connector worker #1 started”

  3. Alternative methods (depending on Zabbix installation):

    • Docker: Set environment variable ZBX_STARTCONNECTORS=1
    • Package installation: Edit /etc/zabbix/zabbix_server.conf and restart service
    • Some installations enable this by default - check logs to confirm

References

Section titled “References”