chore: migrate audit events docs to docsite (#32143)
* chore: migrate audit events docs to docsite Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * change headers Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * fix rebase conflict in sidebars.ts Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * correct sidebar Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> --------- Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
This commit is contained in:
Aramis Sennyey
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/plugin-scaffolder-backend': patch
|
||||
---
|
||||
|
||||
Migrate audit events reference docs to http://backstage.io/docs.
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
'@backstage/plugin-catalog-backend': patch
|
||||
---
|
||||
|
||||
Migrate audit events reference docs to http://backstage.io/docs.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
id: audit-events
|
||||
title: Audit Events
|
||||
description: Tracking access to your Software Catalog.
|
||||
---
|
||||
|
||||
The Catalog backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction within an operation group.
|
||||
|
||||
## Entity Events
|
||||
|
||||
- **`entity-fetch`**: Retrieves entities.
|
||||
- **Note:** By default, "low" severity audit events like `entity-fetch` aren't logged because they map to the "debug" level, while Backstage defaults to "info" level logging. To see `entity-fetch` events, update your `app-config.yaml` by setting `backend.auditor.severityLogLevelMappings.low: info`. See the [Auditor Service documentation](https://backstage.io/docs/backend-system/core-services/auditor/#severity-levels-and-default-mappings) for details on severity mappings.
|
||||
|
||||
Filter on `queryType`.
|
||||
|
||||
- **`all`**: Fetching all entities. (GET `/entities`)
|
||||
- **`by-id`**: Fetching a single entity using its UID. (GET `/entities/by-uid/:uid`)
|
||||
- **`by-name`**: Fetching a single entity using its kind, namespace, and name. (GET `/entities/by-name/:kind/:namespace/:name`)
|
||||
- **`by-query`**: Fetching multiple entities using a filter query. (GET `/entities/by-query`)
|
||||
- **`by-refs`**: Fetching a batch of entities by their entity refs. (POST `/entities/by-refs`)
|
||||
- **`ancestry`**: Fetching the ancestry of an entity. (GET `/entities/by-name/:kind/:namespace/:name/ancestry`)
|
||||
|
||||
- **`entity-mutate`**: Modifies entities.
|
||||
|
||||
Filter on `actionType`.
|
||||
|
||||
- **`delete`**: Deleting a single entity. Note: this will not be a permanent deletion and the entity will be restored if the parent location is still present in the catalog. (DELETE `/entities/by-uid/:uid`)
|
||||
- **`refresh`**: Scheduling an entity refresh. (POST `/entities/refresh`)
|
||||
|
||||
- **`entity-validate`**: Validates an entity. (POST `/entities/validate`)
|
||||
|
||||
- **`entity-facets`**: Retrieves entity facets. (GET `/entity-facets`)
|
||||
|
||||
## Location Events
|
||||
|
||||
- **`location-fetch`**: Retrieves locations.
|
||||
|
||||
Filter on `actionType`.
|
||||
|
||||
- **`all`**: Fetching all locations. (GET `/locations`)
|
||||
- **`by-id`**: Fetching a single location by ID. (GET `/locations/:id`)
|
||||
- **`by-entity`**: Fetching locations associated with an entity ref. (GET `/locations/by-entity`)
|
||||
|
||||
- **`location-mutate`**: Modifies locations.
|
||||
|
||||
- **`create`**: Creating a new location. (POST `/locations`)
|
||||
- **`delete`**: Deleting a location and its associated entities. (DELETE `/locations/:id`)
|
||||
|
||||
- **`location-analyze`**: Analyzes a location. (POST `/locations/analyze`)
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
id: audit-events
|
||||
title: Audit Events
|
||||
description: Tracking access to your Scaffolder.
|
||||
---
|
||||
|
||||
The Scaffolder backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction when needed.
|
||||
|
||||
## Template Events
|
||||
|
||||
- **`template-parameter-schema`**: Retrieves template parameter schemas. (GET `/v2/templates/:namespace/:kind/:name/parameter-schema`)
|
||||
|
||||
## Action Events
|
||||
|
||||
- **`action-fetch`**: Retrieves installed actions. (GET `/v2/actions`)
|
||||
|
||||
## Task Events
|
||||
|
||||
- **`task`**: Operations related to Scaffolder tasks.
|
||||
|
||||
Filter on `actionType`.
|
||||
|
||||
- **`create`**: Creates a new task. (POST `/v2/tasks`)
|
||||
- **`list`**: Fetches details of all tasks. (GET `/v2/tasks`)
|
||||
- **`get`**: Fetches details of a specific task. (GET `/v2/tasks/:taskId`)
|
||||
- **`cancel`**: Cancels a running task. (POST `/v2/tasks/:taskId/cancel`)
|
||||
- **`retry`**: Retries a failed task. (POST `/v2/tasks/:taskId/retry`)
|
||||
- **`stream`**: Retrieves a stream of task logs. (GET `/v2/tasks/:taskId/eventstream`)
|
||||
- **`events`**: Retrieves a snapshot of task logs. (GET `/v2/tasks/:taskId/events`)
|
||||
- **`dry-run`**: Creates a dry-run task. (POST `/v2/dry-run`) All audit logs for events associated with dry runs have the `meta.isDryLog` flag set to `true`.
|
||||
- **`stale-cancel`**: Automated cancellation of stale tasks.
|
||||
- **`execute`**: Tracks the initiation and completion of a real scaffolder task execution. This event will not occur during dry runs.
|
||||
@@ -247,6 +247,7 @@ export default {
|
||||
'features/software-catalog/extending-the-model',
|
||||
'features/software-catalog/external-integrations',
|
||||
'features/software-catalog/catalog-customization',
|
||||
'features/software-catalog/audit-events',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'API',
|
||||
@@ -289,6 +290,7 @@ export default {
|
||||
'features/software-templates/dry-run-testing',
|
||||
'features/software-templates/experimental',
|
||||
'features/software-templates/templating-extensions',
|
||||
'features/software-templates/audit-events',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'API',
|
||||
|
||||
@@ -87,52 +87,6 @@ yarn start
|
||||
This will launch both frontend and backend in the same window, populated with
|
||||
some example entities.
|
||||
|
||||
## Audit Events
|
||||
|
||||
The Catalog backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction within an operation group.
|
||||
|
||||
**Entity Events:**
|
||||
|
||||
- **`entity-fetch`**: Retrieves entities.
|
||||
- **Note:** By default, "low" severity audit events like `entity-fetch` aren't logged because they map to the "debug" level, while Backstage defaults to "info" level logging. To see `entity-fetch` events, update your `app-config.yaml` by setting `backend.auditor.severityLogLevelMappings.low: info`. See the [Auditor Service documentation](https://backstage.io/docs/backend-system/core-services/auditor/#severity-levels-and-default-mappings) for details on severity mappings.
|
||||
|
||||
Filter on `queryType`.
|
||||
|
||||
- **`all`**: Fetching all entities. (GET `/entities`)
|
||||
- **`by-id`**: Fetching a single entity using its UID. (GET `/entities/by-uid/:uid`)
|
||||
- **`by-name`**: Fetching a single entity using its kind, namespace, and name. (GET `/entities/by-name/:kind/:namespace/:name`)
|
||||
- **`by-query`**: Fetching multiple entities using a filter query. (GET `/entities/by-query`)
|
||||
- **`by-refs`**: Fetching a batch of entities by their entity refs. (POST `/entities/by-refs`)
|
||||
- **`ancestry`**: Fetching the ancestry of an entity. (GET `/entities/by-name/:kind/:namespace/:name/ancestry`)
|
||||
|
||||
- **`entity-mutate`**: Modifies entities.
|
||||
|
||||
Filter on `actionType`.
|
||||
|
||||
- **`delete`**: Deleting a single entity. Note: this will not be a permanent deletion and the entity will be restored if the parent location is still present in the catalog. (DELETE `/entities/by-uid/:uid`)
|
||||
- **`refresh`**: Scheduling an entity refresh. (POST `/entities/refresh`)
|
||||
|
||||
- **`entity-validate`**: Validates an entity. (POST `/entities/validate`)
|
||||
|
||||
- **`entity-facets`**: Retrieves entity facets. (GET `/entity-facets`)
|
||||
|
||||
**Location Events:**
|
||||
|
||||
- **`location-fetch`**: Retrieves locations.
|
||||
|
||||
Filter on `actionType`.
|
||||
|
||||
- **`all`**: Fetching all locations. (GET `/locations`)
|
||||
- **`by-id`**: Fetching a single location by ID. (GET `/locations/:id`)
|
||||
- **`by-entity`**: Fetching locations associated with an entity ref. (GET `/locations/by-entity`)
|
||||
|
||||
- **`location-mutate`**: Modifies locations.
|
||||
|
||||
- **`create`**: Creating a new location. (POST `/locations`)
|
||||
- **`delete`**: Deleting a location and its associated entities. (DELETE `/locations/:id`)
|
||||
|
||||
- **`location-analyze`**: Analyzes a location. (POST `/locations/analyze`)
|
||||
|
||||
## Links
|
||||
|
||||
- [catalog](https://github.com/backstage/backstage/tree/master/plugins/catalog)
|
||||
|
||||
@@ -124,32 +124,3 @@ Default secrets are resolved from environment variables and accessible via `${{
|
||||
```
|
||||
|
||||
**Security Note:** Secrets are automatically masked in logs and are only available to backend actions, never exposed to the frontend.
|
||||
|
||||
## Audit Events
|
||||
|
||||
The Scaffolder backend emits audit events for various operations. Events are grouped logically by `eventId`, with `subEventId` providing further distinction when needed.
|
||||
|
||||
**Template Events:**
|
||||
|
||||
- **`template-parameter-schema`**: Retrieves template parameter schemas. (GET `/v2/templates/:namespace/:kind/:name/parameter-schema`)
|
||||
|
||||
**Action Events:**
|
||||
|
||||
- **`action-fetch`**: Retrieves installed actions. (GET `/v2/actions`)
|
||||
|
||||
**Task Events:**
|
||||
|
||||
- **`task`**: Operations related to Scaffolder tasks.
|
||||
|
||||
Filter on `actionType`.
|
||||
|
||||
- **`create`**: Creates a new task. (POST `/v2/tasks`)
|
||||
- **`list`**: Fetches details of all tasks. (GET `/v2/tasks`)
|
||||
- **`get`**: Fetches details of a specific task. (GET `/v2/tasks/:taskId`)
|
||||
- **`cancel`**: Cancels a running task. (POST `/v2/tasks/:taskId/cancel`)
|
||||
- **`retry`**: Retries a failed task. (POST `/v2/tasks/:taskId/retry`)
|
||||
- **`stream`**: Retrieves a stream of task logs. (GET `/v2/tasks/:taskId/eventstream`)
|
||||
- **`events`**: Retrieves a snapshot of task logs. (GET `/v2/tasks/:taskId/events`)
|
||||
- **`dry-run`**: Creates a dry-run task. (POST `/v2/dry-run`) All audit logs for events associated with dry runs have the `meta.isDryLog` flag set to `true`.
|
||||
- **`stale-cancel`**: Automated cancellation of stale tasks.
|
||||
- **`execute`**: Tracks the initiation and completion of a real scaffolder task execution. This event will not occur during dry runs.
|
||||
|
||||
Reference in New Issue
Block a user