--- 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 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](/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` | | `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 ```shell-session # Subscribe to all events and topics $ curl -s -v -N http://127.0.0.1:4646/v1/event/stream ``` ```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 } } } ] } ```