Events HTTP API

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

Event Stream

This endpoint streams a servers backlog of events as well as new events as they occur. The stream will be kept alive until the connection is closed.

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
ACLToken management
ACLPolicy management
Job namespace:read-job
Allocation namespace:read-job
Deployment namespace:read-job
Evaluation namespace:read-job
Node node:read

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.

  • 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
ACLToken ACLToken
ACLPolicy ACLPolicy
Allocation Allocation (no job information)
Job Job
Evaluation Evaluation
Deployment Deployment
Node Node
NodeDrain Node

Event Types

Type
ACLTokenUpserted
ACLTokenDeleted
ACLPolicyUpserted
ACLPolicyDeleted
AllocationCreated
AllocationUpdated
AllocationUpdateDesiredStatus
DeploymentStatusUpdate
DeploymentPromotion
DeploymentAllocHealth
EvaluationUpdated
JobRegistered
JobDeregistered
JobBatchDeregistered
NodeRegistration
NodeDeregistration
NodeEligibility
NodeDrain
NodeEvent
PlanResult

Sample Request

# Subscribe to all events and topics
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream
# 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": "true",
            "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"
            },
            "mock_driver": {
              "Attributes": {
                "driver.mock": "true"
              },
              "Detected": true,
              "Healthy": true,
              "HealthDescription": "Healthy",
              "UpdateTime": "2020-10-15T10:07:37.445193068-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
        }
      }
    }
  ]
}