Zabbix

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

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

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

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

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

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

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

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

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

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

• 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

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

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

• Streaming to external systems - Official Zabbix configuration guide
• Connector API reference - Zabbix API documentation