Events HTTP API

The /event/stream endpoint is used to stream events generated by Nomad.

Event Stream

This endpoint streams a server's backlog of events as well as new events as they occur. The stream will be kept alive until the connection is closed. The format of the response body will be valid ndjson. This means splitting the streaming response at every \n character will guarantee each message is a valid JSON object. Note that each JSON object may include multiple events (high server activity) or no events (heartbeating to keep the connection open).

Method	Path	Produces
`GET`	`/v1/event/stream`	`application/json`

The table below shows this endpoint's required ACLs. Due to the nature of this endpoint individual topics require specific policies.

Note that if you do not include a topic parameter all topics will be included by default, requiring a management token.

Topic	ACL Required
`*`	`management`
`ACLPolicy`	`management`
`ACLRole`	`management`
`ACLToken`	`management`
`Allocation`	`namespace:read-job`
`Deployment`	`namespace:read-job`
`Evaluation`	`namespace:read-job`
`HostVolume`	`namespace:host-volume-read`
`Job`	`namespace:read-job`
`NodePool`	`management`
`Node`	`node:read`
`Service`	`namespace:read-job`

Parameters

index (int: 0) - Specifies the index to start streaming events from. If the requested index is no longer in the buffer the stream will start at the next available index.
namespace (string: "default") - Specifies the target namespace to filter on. Specifying * includes all namespaces for event types that support namespaces. If you specify all namespaces (*) you'll either need a management token, or an ACL Policy that explicitly applies to all namespaces (*).
topic (topic:filter_key: "*:*") - Specifies a topic to subscribe to and filter on. The default is to subscribe to all topics. Multiple topics may be specified by passing multiple topic parameters. A valid topic parameter includes a topic type and an optional filter_key separated by a colon :. As an example ?topic=Deployment:redis would subscribe to all Deployment events for a job redis. an additional topic &topic=Deployment:web would include deployment events for redis and web. To only subscribe to Node events a topic parameter of ?topic=Node without a separator value would be used. ?topic=Node:* is also valid.

Event Topics

Topic	Output
ACLPolicy	ACLPolicy
ACLRoles	ACLRole
ACLToken	ACLToken
Allocation	Allocation (no job information)
Deployment	Deployment
Evaluation	Evaluation
HostVolume	HostVolume (dynamic host volumes only)
Job	Job
Node	Node
NodeDrain	Node
NodePool	NodePool
Service	Service Registrations

Event Types

Type
ACLPolicyDeleted
ACLPolicyUpserted
ACLRoleDeleted
ACLRoleUpserted
ACLTokenDeleted
ACLTokenUpserted
AllocationCreated
AllocationUpdateDesiredStatus
AllocationUpdated
DeploymentAllocHealth
DeploymentPromotion
DeploymentStatusUpdate
EvaluationUpdated
HostVolumeDeleted
HostVolumeRegistered
JobBatchDeregistered
JobDeregistered
JobRegistered
NodeDeregistration
NodeDrain
NodeEligibility
NodeEvent
NodePoolDeleted
NodePoolUpserted
NodeRegistration
PlanResult
ServiceDeregistration
ServiceRegistration

Sample Request

# Subscribe to all events and topics in the default namespace
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream

# Subscribe to all events and topics in all namespaces
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream?namespace=*

# Start at index 100 and subscribe to all Evaluation events
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream?index=100&topic=Evaluation

$ curl -G -s -v -N \
--data-urlencode "topic=Node:ccc4ce56-7f0a-4124-b8b1-a4015aa82c40" \
--data-urlencode "topic=Deployment" \
--data-urlencode "topic=Job:web" \
http://127.0.0.1:4646/v1/event/stream

Sample Response

{
  "Index": 7,
  "Events": [
    {
      "Topic": "Node",
      "Type": "NodeRegistration",
      "Key": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
      "Namespace": "",
      "FilterKeys": null,
      "Index": 7,
      "Payload": {
        "Node": {
          "ID": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
          "Datacenter": "dc1",
          "Name": "nomad-4",
          "HTTPAddr": "127.0.0.1:4646",
          "TLSEnabled": false,
          "Attributes": {
            "cpu.arch": "amd64",
            "cpu.frequency": "4200",
            "cpu.modelname": "Intel(R) Core(TM) i7-8650U CPU @ 1.90GHz",
            "cpu.numcores": "8",
            "cpu.totalcompute": "33600",
            "driver.docker": "1",
            "driver.docker.bridge_ip": "172.17.0.1",
            "driver.docker.os_type": "linux",
            "driver.docker.runtimes": "runc",
            "driver.docker.version": "19.03.13",
            "driver.mock_driver": "1",
            "driver.raw_exec": "1",
            "kernel.name": "linux",
            "kernel.version": "5.4.0-48-generic",
            "memory.totalbytes": "16525733888",
            "nomad.advertise.address": "127.0.0.1:4646",
            "nomad.revision": "8c88f29bff0849720e33b0cc73af87495358f3b8",
            "nomad.version": "0.13.0-dev",
            "os.name": "ubuntu",
            "os.signals": "SIGBUS,SIGFPE,SIGTRAP,SIGTTOU,SIGWINCH,SIGXFSZ,SIGHUP,SIGILL,SIGALRM,SIGCHLD,SIGSYS,SIGXCPU,SIGPROF,SIGQUIT,SIGTERM,SIGUSR2,SIGCONT,SIGIO,SIGSEGV,SIGTTIN,SIGIOT,SIGKILL,SIGPIPE,SIGABRT,SIGINT,SIGSTOP,SIGTSTP,SIGURG,SIGUSR1",
            "os.version": "20.04",
            "unique.cgroup.mountpoint": "/sys/fs/cgroup/systemd",
            "unique.hostname": "x1c",
            "unique.network.ip-address": "127.0.0.1",
            "unique.storage.bytesfree": "299488927744",
            "unique.storage.bytestotal": "502468108288",
            "unique.storage.volume": "/dev/nvme0n1p2"
          },
          "NodeResources": {
            "Cpu": {
              "CpuShares": 33600
            },
            "Memory": {
              "MemoryMB": 15760
            },
            "Disk": {
              "DiskMB": 285614
            },
            "Networks": [
              {
                "Mode": "bridge",
                "Device": "",
                "CIDR": "",
                "IP": "",
                "MBits": 0,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "127.0.0.1/32",
                "IP": "127.0.0.1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "::1/128",
                "IP": "::1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              }
            ],
            "NodeNetworks": [
              {
                "Mode": "bridge",
                "Device": "",
                "MacAddress": "",
                "Speed": 0,
                "Addresses": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "MacAddress": "",
                "Speed": 1000,
                "Addresses": [
                  {
                    "Family": "ipv4",
                    "Alias": "default",
                    "Address": "127.0.0.1",
                    "ReservedPorts": "",
                    "Gateway": ""
                  },
                  {
                    "Family": "ipv6",
                    "Alias": "default",
                    "Address": "::1",
                    "ReservedPorts": "",
                    "Gateway": ""
                  }
                ]
              }
            ],
            "Devices": null
          },
          "ReservedResources": {
            "Cpu": {
              "CpuShares": 0
            },
            "Memory": {
              "MemoryMB": 0
            },
            "Disk": {
              "DiskMB": 0
            },
            "Networks": {
              "ReservedHostPorts": ""
            }
          },
          "Resources": {
            "CPU": 33600,
            "MemoryMB": 15760,
            "DiskMB": 285614,
            "IOPS": 0,
            "Networks": [
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "127.0.0.1/32",
                "IP": "127.0.0.1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              },
              {
                "Mode": "host",
                "Device": "lo",
                "CIDR": "::1/128",
                "IP": "::1",
                "MBits": 1000,
                "DNS": null,
                "ReservedPorts": null,
                "DynamicPorts": null
              }
            ],
            "Devices": null
          },
          "Reserved": {
            "CPU": 0,
            "MemoryMB": 0,
            "DiskMB": 0,
            "IOPS": 0,
            "Networks": null,
            "Devices": null
          },
          "Links": null,
          "Meta": {
            "connect.gateway_image": "envoyproxy/envoy:v1.11.2@sha256:a7769160c9c1a55bb8d07a3b71ce5d64f72b1f665f10d81aa1581bc3cf850d09",
            "connect.log_level": "info",
            "connect.sidecar_image": "envoyproxy/envoy:v1.11.2@sha256:a7769160c9c1a55bb8d07a3b71ce5d64f72b1f665f10d81aa1581bc3cf850d09"
          },
          "NodeClass": "",
          "ComputedClass": "v1:9803688035578634002",
          "Drain": false,
          "DrainStrategy": null,
          "SchedulingEligibility": "eligible",
          "Status": "initializing",
          "StatusDescription": "",
          "StatusUpdatedAt": 1602770857,
          "Events": [
            {
              "Message": "Node registered",
              "Subsystem": "Cluster",
              "Details": null,
              "Timestamp": "2020-10-15T10:07:37-04:00",
              "CreateIndex": 0
            }
          ],
          "Drivers": {
            "docker": {
              "Attributes": {
                "driver.docker": "true",
                "driver.docker.bridge_ip": "172.17.0.1",
                "driver.docker.os_type": "linux",
                "driver.docker.runtimes": "runc",
                "driver.docker.version": "19.03.13"
              },
              "Detected": true,
              "Healthy": true,
              "HealthDescription": "Healthy",
              "UpdateTime": "2020-10-15T10:07:37.904159516-04:00"
            },
            "exec": {
              "Attributes": null,
              "Detected": false,
              "Healthy": false,
              "HealthDescription": "Driver must run as root",
              "UpdateTime": "2020-10-15T10:07:37.445083368-04:00"
            },
            "java": {
              "Attributes": null,
              "Detected": false,
              "Healthy": false,
              "HealthDescription": "Driver must run as root",
              "UpdateTime": "2020-10-15T10:07:37.445601605-04:00"
            },
            "qemu": {
              "Attributes": null,
              "Detected": false,
              "Healthy": false,
              "HealthDescription": "",
              "UpdateTime": "2020-10-15T10:07:37.445684857-04:00"
            },
            "raw_exec": {
              "Attributes": {
                "driver.raw_exec": "true"
              },
              "Detected": true,
              "Healthy": true,
              "HealthDescription": "Healthy",
              "UpdateTime": "2020-10-15T10:07:37.445431163-04:00"
            }
          },
          "CSIControllerPlugins": null,
          "CSINodePlugins": null,
          "HostVolumes": null,
          "CreateIndex": 7,
          "ModifyIndex": 7
        }
      }
    }
  ]
}