From 77eb0135188b49cf4c47a4c799f39ffc7830c854 Mon Sep 17 00:00:00 2001 From: peterschmidt85 Date: Tue, 27 Jan 2026 16:28:40 +0100 Subject: [PATCH 1/7] [Docs] Events #3397 --- docs/docs/concepts/events.md | 70 +++++++++++++++++++++++++ docs/docs/reference/cli/dstack/event.md | 5 +- mkdocs.yml | 4 +- 3 files changed, 75 insertions(+), 4 deletions(-) create mode 100644 docs/docs/concepts/events.md diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md new file mode 100644 index 0000000000..4bc78e1610 --- /dev/null +++ b/docs/docs/concepts/events.md @@ -0,0 +1,70 @@ +# Events + +Events provide a complete, chronological record of state changes across all resources. They are designed for auditing, debugging, and understanding the lifecycle of runs, jobs, fleets, and other resources. + +Each event includes the following fields: + +| Field | Description | +| --------- | ----------------------------------------------------------- | +| Timestamp | When the event occurred | +| Actor | The user or system that initiated the change, if applicable | +| Target | The resource affected by the event | +| Message | A description of the change or additional event details | + +Events can be queried by targeting a specific resource or within a group of related resources. For example, you can query events targeting a particular job or within a run, including the run itself and all of its associated resources. + +Events are accessible through the UI, CLI, and API. + +## UI + +The UI allows you to query events either globally on the dedicated `Events` page or within a specific group on the page of a run, job, fleet, instance, and other resources. + +### Global page + +The global page shows events from all projects that the user has access to and allows filtering by many fields. + +![](https://dstack.ai/static-assets/static-assets/images/dstack-ui-events-global.png){ width=800 } + +This page allows you to query events targeting a specific resource or within a particular group. + +### Resource page + +The resource page shows events within that specific group. For example, if you open a run and switch to the `Events` tab, you will see all events within that run, including events targeting individual jobs, fleet instances, and other related resources. + +![](https://dstack.ai/static-assets/static-assets/images/dstack-ui-events-run.png){ width=800 } + +## CLI + +To query events via the CLI, use the `dstack event` command. This command provides several arguments that allow filtering by target and within scopes. + +Here is an example of querying all events within a particular run: + +
+ +```shell +$ dstack event --within-run cursor + +[2026-01-21 13:09:37] [👤admin] [run cursor] Run submitted. Status: SUBMITTED +[2026-01-21 13:09:37] [job cursor-0-0] Job created on run submission. Status: SUBMITTED +[2026-01-21 13:09:57] [job cursor-0-0] Job status changed SUBMITTED -> PROVISIONING +[2026-01-21 13:09:58] [job cursor-0-0, instance some-fleet-0] Instance created for job. Instance status: PROVISIONING +[2026-01-21 13:09:59] [run cursor] Run status changed SUBMITTED -> PROVISIONING +[2026-01-21 13:11:22] [job cursor-0-0] Job status changed PROVISIONING -> PULLING +[2026-01-21 13:11:49] [job cursor-0-0] Job status changed PULLING -> RUNNING +[2026-01-21 13:11:51] [run cursor] Run status changed PROVISIONING -> RUNNING +[2026-01-21 13:18:41] [👤admin] [run cursor] Run status changed RUNNING -> TERMINATING. Termination reason: STOPPED_BY_USER +[2026-01-21 13:18:48] [job cursor-0-0] Job status changed RUNNING -> TERMINATING. Termination reason: TERMINATED_BY_USER +[2026-01-21 13:19:05] [instance some-fleet-0, job cursor-0-0] Job unassigned from instance. Instance blocks: 0/1 busy +[2026-01-21 13:19:05] [job cursor-0-0] Job status changed TERMINATING -> TERMINATED +[2026-01-21 13:19:07] [run cursor] Run status changed TERMINATING -> TERMINATED +``` + +
+ +To see all supported arguments, check the [reference](../reference/cli/dstack/event.md). + +If you invoke the command without arguments, it will include all events targeting resources in the project. + +## TTL + +By default, `dstack` stores each event for 30 days and then deletes it. This can be overridden by changing the `DSTACK_SERVER_EVENTS_TTL_SECONDS` environment variable. diff --git a/docs/docs/reference/cli/dstack/event.md b/docs/docs/reference/cli/dstack/event.md index 9854609208..8f90e456c9 100644 --- a/docs/docs/reference/cli/dstack/event.md +++ b/docs/docs/reference/cli/dstack/event.md @@ -1,9 +1,8 @@ # dstack event -The `dstack event` command (an alias for `dstack event list`) allows you to view events. - - +The `dstack event` command, an alias for `dstack event list`, allows you to view events. +For more details, see [Events](../../../concepts/events.md). ## Usage diff --git a/mkdocs.yml b/mkdocs.yml index 5dcdd69999..c7afe30256 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,7 +77,8 @@ plugins: - docs/concepts/gateways.md: How to manage gateways - enabling auto-scaling, rate limits, and custom domains - docs/concepts/secrets.md: How to manage secrets - for API keys or other sensitive data - docs/concepts/projects.md: How to manage projects - for managing separate teams - - docs/concepts/metrics.md: How to manage gateways - enabling auto-scaling, rate limits, and custom domains + - docs/concepts/metrics.md: How to access metrics - for monitoring of runs/jobs/fleets, hardware usage (e.g. GPU util), etc + - docs/concepts/events.md: How to access events - aka audit log - for tracking state changes, resource creation/deletion, etc Guides: - docs/guides/server-deployment.md: Detailed guide on how to deploy the dstack server - docs/guides/troubleshooting.md: Common issues and how to troubleshoot them @@ -271,6 +272,7 @@ nav: - Secrets: docs/concepts/secrets.md - Projects: docs/concepts/projects.md - Metrics: docs/concepts/metrics.md + - Events: docs/concepts/events.md - Guides: - Server deployment: docs/guides/server-deployment.md - Troubleshooting: docs/guides/troubleshooting.md From 12a224963e241e452550affd51e4fcb9efcd8f12 Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Tue, 27 Jan 2026 19:58:17 +0100 Subject: [PATCH 2/7] Update docs/docs/concepts/events.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md index 4bc78e1610..e568c10142 100644 --- a/docs/docs/concepts/events.md +++ b/docs/docs/concepts/events.md @@ -8,7 +8,7 @@ Each event includes the following fields: | --------- | ----------------------------------------------------------- | | Timestamp | When the event occurred | | Actor | The user or system that initiated the change, if applicable | -| Target | The resource affected by the event | +| Targets | The resources affected by the event | | Message | A description of the change or additional event details | Events can be queried by targeting a specific resource or within a group of related resources. For example, you can query events targeting a particular job or within a run, including the run itself and all of its associated resources. From e186b8eead4e4673ab5254b727f2f7d28a96f284 Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Tue, 27 Jan 2026 20:02:52 +0100 Subject: [PATCH 3/7] Update docs/docs/concepts/events.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md index e568c10142..ae944faa87 100644 --- a/docs/docs/concepts/events.md +++ b/docs/docs/concepts/events.md @@ -11,7 +11,7 @@ Each event includes the following fields: | Targets | The resources affected by the event | | Message | A description of the change or additional event details | -Events can be queried by targeting a specific resource or within a group of related resources. For example, you can query events targeting a particular job or within a run, including the run itself and all of its associated resources. +Events can be queried by targeting a specific resource or within a group of related resources. For example, you can query events targeting a particular job, or query events within a run, including the run itself and all of its jobs. Events are accessible through the UI, CLI, and API. From a416af6710d167697f83f53612be21a47f0746e9 Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Tue, 27 Jan 2026 20:03:02 +0100 Subject: [PATCH 4/7] Update docs/docs/concepts/events.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md index ae944faa87..f96b30548b 100644 --- a/docs/docs/concepts/events.md +++ b/docs/docs/concepts/events.md @@ -17,7 +17,7 @@ Events are accessible through the UI, CLI, and API. ## UI -The UI allows you to query events either globally on the dedicated `Events` page or within a specific group on the page of a run, job, fleet, instance, and other resources. +The UI allows you to query events either globally on the dedicated `Events` page or within a specific group on the page of a run, job, fleet, and other resources. ### Global page From 613dffde30cefd3b53443613ae4c3131e269d995 Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Tue, 27 Jan 2026 20:03:17 +0100 Subject: [PATCH 5/7] Update docs/docs/concepts/events.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md index f96b30548b..38bfa2887c 100644 --- a/docs/docs/concepts/events.md +++ b/docs/docs/concepts/events.md @@ -29,7 +29,7 @@ This page allows you to query events targeting a specific resource or within a p ### Resource page -The resource page shows events within that specific group. For example, if you open a run and switch to the `Events` tab, you will see all events within that run, including events targeting individual jobs, fleet instances, and other related resources. +The resource page shows events within that specific group. For example, if you open a run and switch to the `Events` tab, you will see all events about that run and its jobs. ![](https://dstack.ai/static-assets/static-assets/images/dstack-ui-events-run.png){ width=800 } From b3943595d623fb15d812209f2ca1a0eda577c45b Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Tue, 27 Jan 2026 20:03:23 +0100 Subject: [PATCH 6/7] Update docs/docs/concepts/events.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md index 38bfa2887c..a3cdf53bad 100644 --- a/docs/docs/concepts/events.md +++ b/docs/docs/concepts/events.md @@ -67,4 +67,4 @@ If you invoke the command without arguments, it will include all events targetin ## TTL -By default, `dstack` stores each event for 30 days and then deletes it. This can be overridden by changing the `DSTACK_SERVER_EVENTS_TTL_SECONDS` environment variable. +By default, `dstack` stores each event for 30 days and then deletes it. This can be overridden by server administrators using the `DSTACK_SERVER_EVENTS_TTL_SECONDS` environment variable. From 08e6c5e1adda2b053d92c38e1caf0c1a8e11309e Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Tue, 27 Jan 2026 20:03:39 +0100 Subject: [PATCH 7/7] Update docs/docs/concepts/events.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/events.md b/docs/docs/concepts/events.md index a3cdf53bad..fb6e0938a2 100644 --- a/docs/docs/concepts/events.md +++ b/docs/docs/concepts/events.md @@ -1,6 +1,6 @@ # Events -Events provide a complete, chronological record of state changes across all resources. They are designed for auditing, debugging, and understanding the lifecycle of runs, jobs, fleets, and other resources. +Events provide a chronological record of notable state changes and operations affecting `dstack` resources. They are designed for auditing, debugging, and understanding the lifecycle of runs, jobs, fleets, and other resources. Each event includes the following fields: