github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/events.mdx

---
layout: api
page_title: Events - HTTP API
description: |-
  The /event endpoints are used to query for and stream Nomad events.
---

# 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](http://ndjson.org/). 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](/api-docs#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`         |
| `ACLRole`    | `management`         |
| `Job`        | `namespace:read-job` |
| `Allocation` | `namespace:read-job` |
| `Deployment` | `namespace:read-job` |
| `Evaluation` | `namespace:read-job` |
| `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                          |
| ---------- | ------------------------------- |
| ACLToken   | ACLToken                        |
| ACLPolicy  | ACLPolicy                       |
| ACLRoles   | ACLRole                         |
| Allocation | Allocation (no job information) |
| Job        | Job                             |
| Evaluation | Evaluation                      |
| Deployment | Deployment                      |
| Node       | Node                            |
| NodeDrain  | Node                            |
| Service    | Service Registrations           |

### Event Types

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

### Sample Request

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

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

```shell-session
# 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
```

```shell-session
$ 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

```json
{
  "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
        }
      }
    }
  ]
}
```