NSQ

Auto-Detection

Built-in Metrics

Exporter Metrics

NSQ is a real-time distributed messaging platform designed for high-throughput, fault-tolerant message delivery.

Glouton can monitor NSQ in two ways:

• Auto-detection — recommended, minimal configuration. Glouton detects NSQ and collects a curated set of built-in metrics directly from nsqd’s stats API.
• Exporter metrics — collect a more detailed set of metrics through a third-party Prometheus exporter.

Auto-Detection

Glouton detects NSQ by its nsqd process and listening port (default HTTP stats API: 4151). Metrics are read directly from the stats API — no exporter or authentication is required.

If the auto-detected parameters are incorrect, override them manually:

Linux

sudo tee /etc/glouton/conf.d/99-nsq.conf > /dev/null << 'EOF'
service:
  - type: "nsq"
    address: "127.0.0.1"
    port: 4151
EOF

Windows

Create or edit C:\ProgramData\glouton\conf.d\99-nsq.conf:

service:
  - type: "nsq"
    address: "127.0.0.1"
    port: 4151

Glouton automatically detects configuration changes.

Metric	Description
service_status	Status of NSQ
nsq_server_servers	Number of nsqd servers reporting
nsq_server_topics	Number of topics on the nsqd server
nsq_topic_depth	Number of messages currently queued in a topic
nsq_topic_messages	Total number of messages received by a topic
nsq_channel_depth	Number of messages currently queued in a channel
nsq_channel_messages	Total number of messages received by a channel
nsq_channel_clients	Number of clients currently connected to a channel
nsq_channel_inflights	Number of messages currently in flight for a channel
nsq_channel_requeues	Total number of messages requeued on a channel
nsq_channel_timeouts	Total number of messages that timed out on a channel

Exporter Metrics

Detailed NSQ metrics are collected using the third-party nsq_exporter.

Prerequisites

• NSQ (nsqd) installed and running with the HTTP interface enabled (port 4151 by default)
• Glouton agent installed on the same host
• Go toolchain (if building from source) or access to GitHub releases

Installing the Exporter

Download the latest release from the nsq_exporter releases page, or install with Go:

go install github.com/lovoo/nsq_exporter@latest

Start the exporter:

nsq_exporter --nsqd.addr="http://localhost:4151"

The exporter listens on port 9117 by default. Verify it is working:

curl http://localhost:9117/metrics

For production use, create a systemd service unit to manage the exporter process.

Glouton Configuration

Linux

sudo tee /etc/glouton/conf.d/99-nsq.conf > /dev/null << 'EOF'
metric:
  prometheus:
    targets:
      - url: "http://localhost:9117/metrics"
        name: "nsq"
        allow_metrics:
          - "nsq_topic_message_count"
          - "nsq_topic_depth"
          - "nsq_channel_message_count"
          - "nsq_channel_depth"
          - "nsq_channel_in_flight_count"
          - "nsq_channel_timeout_count"
EOF

Windows

Create or edit C:\ProgramData\glouton\conf.d\99-nsq.conf:

metric:
  prometheus:
    targets:
      - url: "http://localhost:9117/metrics"
        name: "nsq"
        allow_metrics:
          - "nsq_topic_message_count"
          - "nsq_topic_depth"
          - "nsq_channel_message_count"
          - "nsq_channel_depth"
          - "nsq_channel_in_flight_count"
          - "nsq_channel_timeout_count"

Glouton automatically detects configuration changes.

Customize collected metrics

The metrics below are our recommended defaults. You can adjust the allow_metrics list to include any metric from the nsq_exporter GitHub repository, or use deny_metrics to exclude specific ones. See Metrics Filtering for details.

Metric	Description
nsq_topic_message_count	Total number of messages published to a topic
nsq_topic_depth	Number of messages currently queued in a topic
nsq_channel_message_count	Total number of messages delivered to a channel
nsq_channel_depth	Number of messages currently queued in a channel
nsq_channel_in_flight_count	Number of messages currently in flight for a channel
nsq_channel_timeout_count	Total number of timed-out messages for a channel

Monitoring Troubleshooting

See Troubleshoot a Service Check or Missing Metrics for what applies to every service: finding the address and port Glouton really uses, what each check message means, and how to read the collection error — which does not appear in the agent logs at the default level.

The Service Check is not OK

The check only opens the TCP port — it sends no command — so it fails when the port is wrong (Connection refused), when a firewall drops the packets (connection timed out after 10 seconds), or when the configured address cannot be parsed (Invalid TCP address). A green check proves the port is open, and nothing more.

Metrics are Missing

A passing check says nothing about the metrics: they are collected separately.

Metrics come from the nsqd HTTP stats API — stats_url if set, otherwise the detected address and port. No authentication is involved.

Reproduce what Glouton does, from the machine where the agent runs:

curl -s "http://127.0.0.1:4151/stats?format=json" | head -c 200

What you see	Cause	Fix
a protocol error	Glouton points at the TCP protocol port (4150) instead of the HTTP API (4151)	Set port: 4151, or stats_url
a connection error	nsqd is bound to an address the agent cannot reach	Set address, or bind --http-address accordingly
no metric, and no error	Only nsqlookupd runs on this host	The metrics come from nsqd; there is nothing to gather from nsqlookupd