nsqadmin

nsqadmin is a Web UI to view aggregated cluster stats in realtime and perform various administrative tasks.

Command Line Options

-acl-http-header string
    HTTP header to check for authenticated admin users (default "X-Forwarded-User")
-admin-user value
    admin user (may be given multiple times; if specified, only these users will be able to perform privileged actions; acl-http-header is used to determine the authenticated user)
-allow-config-from-cidr string
    A CIDR from which to allow HTTP requests to the /config endpoint (default "127.0.0.1/8")
-base-path string
    URL base path (default "/")
-config string
    path to config file
-graphite-url string
    graphite HTTP address
-http-address string
    <addr>:<port> to listen on for HTTP clients (default "0.0.0.0:4171")
-http-client-connect-timeout duration
    timeout for HTTP connect (default 2s)
-http-client-request-timeout duration
    timeout for HTTP request (default 5s)
-http-client-tls-cert string
    path to certificate file for the HTTP client
-http-client-tls-insecure-skip-verify
    configure the HTTP client to skip verification of TLS certificates
-http-client-tls-key string
    path to key file for the HTTP client
-http-client-tls-root-ca-file string
    path to CA file for the HTTP client
-log-level value
    set log verbosity: debug, info, warn, error, or fatal (default INFO)
-log-prefix string
    log message prefix (default "[nsqadmin] ")
-lookupd-http-address value
    lookupd HTTP address (may be given multiple times)
-notification-http-endpoint string
    HTTP endpoint (fully qualified) to which POST notifications of admin actions will be sent
-nsqd-http-address value
    nsqd HTTP address (may be given multiple times)
-proxy-graphite
    proxy HTTP requests to graphite
-statsd-counter-format string
    The counter stats key formatting applied by the implementation of statsd. If no formatting is desired, set this to an empty string. (default "stats.counters.%s.count")
-statsd-gauge-format string
    The gauge stats key formatting applied by the implementation of statsd. If no formatting is desired, set this to an empty string. (default "stats.gauges.%s")
-statsd-interval duration
    time interval nsqd is configured to push to statsd (must match nsqd) (default 1m0s)
-statsd-prefix string
    prefix used for keys sent to statsd (%s for host replacement, must match nsqd) (default "nsq.%s")
-verbose
    [deprecated] has no effect, use --log-level
-version
    print version string

statsd / Graphite Integration

When using nsqd --statsd-address=... you can specify a nsqadmin --graphite-url=https://graphite.yourdomain.com to enable graphite charts in nsqadmin. If using a statsd clone (like statsdaemon) that does not prefix keys, also specify --use-statsd-prefix=false.

Admin Notifications

If the --notification-http-endpoint flag is set, nsqadmin will send a POST request to the specified (fully qualified) endpoint each time an admin action (such as pausing a channel) is performed.

The body of the request contains information about the action (some fields will be omitted when appropriate), like so:

{
  "action": "unpause_channel",
  "channel": "mouth",
  "topic": "beer",
  "timestamp": 1357683731,
  "user": "df",
  "user_agent": "Mozilla/5.0 (Macintosh; Iphone 8)",
  "remote_ip": "1.2.3.4:5678",
  "url": "http://nsqadmin.local/api/topics/api_requests/nsq_to_file",
  "via": "localhost"
}

The user field will be filled if a HTTP Basic Authentication Username is present in the request made to nsqadmin, say if it were running with htpasswd authentication or behind oauth2_proxy.

Hint: You can create an NSQ stream of admin action notifications with the topic name admin_actions by setting --notification-http-endpoint to point to the nsqd HTTP Publish API. For example if running nsqd on the same node you could use --notification-http-endpoint="http://127.0.0.1:4151/put?topic=admin_actions"

There are community contributed utilities nsqadmin2slack and nsqadmin2hipchat to relay messages to HipChat and Slack respectively.

Actions that are captured are:

  • create_channel
  • create_topic
  • delete_channel
  • delete_topic
  • empty_channel
  • empty_topic
  • pause_channel
  • pause_topic
  • tombstone_topic_producer
  • unpause_channel
  • unpause_topic

Metrics

The following metrics are exposed through nsqadmin on Topic, Channel and Client Connections.

Message Queues:

  • Depth: Current sum of messages in memory + on disk (i.e. the “backlog” of messages pending delivery).
  • In-Flight: Current count of messages delivered but not yet finished (FIN), requeued (REQ) or timed out.
  • Deferred: Current count of messages that were requeued and explicitly deferred which are not yet available for delivery.

Statistics:

  • Requeued: Total times a message has been added back to the queue due to time outs or explicit requeues.
  • Timed Out: Total times a message has been requeued after not receiving a response from the client before the configured timeout.
  • Messages: Total count of new messages recieved since node startup.
  • Rate: The per-second rate of new messages over the previous two statsd intervals (available only when graphite integration is enabled).
  • Connections: Current number of connected clients.

Client Connections:

  • Client Host: Client ID (hostname) and on-hover the connection remote-address.
  • Protocol: NSQ protocol version and client user-agent.
  • Attributes: TLS and AUTH connection state.
  • NSQd Host: Address of the nsqd node this client is connected to.
  • In-flight: Current count of messages awaiting response that have been delivered to this client.
  • Ready Count: Max number of messages that can be in-flight on this connection. This is controlled by a client’s max_in_flight setting.
  • Finished: Total count of messages that this client has finished (FIN).
  • Requeued: Total count of messages that this client has requeued (REQ).
  • Messages: Total count of messages delivered to this client.