WIP events/React docs

docs/3.0rc/react/incidents.mdx

@@ -0,0 +1,91 @@
+---
+title: Incidents
+description: Incidents in Prefect Cloud help identify, resolve, and document issues in mission-critical workflows.
+---
+
+Incidents help you manage inevitable workflow disruptions, minimize their impact, and ensure operational continuity. With incidents, you can identify, resolve, and document issues with workflows, facilitating collaboration and compliance.
+
+
+Incidents vary in nature and severity, ranging from minor glitches to critical system failures. With [automations](#incident-automations), activity in a workspace can be paused when an incident is created and resumed when the incident is resolved.
+
+
+
+
+Incorporating incidents into your Prefect workflow facilitates:
+
+* **Automated detection and reporting**, Incidents can be automatically identified based on specific triggers or manually reported by team members, facilitating prompt response
+
+* **Collaborative problem solving**, The platform fosters collaboration, allowing team members to share insights, discuss resolutions, and track contributions
+
+* **Comprehensive impact assessment**, Users gain insights into the incident's influence on workflows, helping in prioritizing response efforts
+
+* **Compliance with incident management processes**, Detailed documentation and reporting features support compliance with incident management systems
+
+* **Enhanced operational transparency**, The system provides a transparent view of both ongoing and resolved incidents, promoting accountability and continuous improvement
+
+## Incident management in Prefect Cloud
+
+Prefect Cloud provides tools for managing the entire incident lifecycle, from creation to retrospective reporting. 
+
+### Create an incident
+
+There are several ways to create an incident:
+
+* **From the Incidents page**, click the **+** button, fill in required fields, and attach any Prefect resources related to your incident.
+
+* **From a flow run, work pool, or block**, from the failed flow run, click the menu button and select "Declare an incident". This method automatically links the resource. 
+
+* **Through an [automation](/3.0rc/react/understand-events/automations-triggers/)**, set up incident creation as an automated response to selected triggers.
+
+### Automate an incident
+
+Automations can be used for triggering an incident and for taking action when an incident is triggered. For example, a work pool status change could trigger the declaration of an incident, or a critical level incident could trigger a notification action.
+
+To automatically take action when an incident is declared, set up a custom trigger that listens for declaration events:
+
+```json
+{
+  "match": {
+    "prefect.resource.id": "prefect-cloud.incident.*"
+  },
+  "expect": [
+    "prefect-cloud.incident.declared"
+  ],
+  "posture": "Reactive",
+  "threshold": 1,
+  "within": 0
+}
+```
+
+To get started with incident automations, specify two fields in your trigger:
+
+  - **match**, the resource emitting your event of interest. You can match on specific resource IDs, use wildcards to match on all resources of a given type, and even match on other resource attributes, like `prefect.resource.name`.
+
+  - **expect**, the event type to listen for. For example, you could listen for any (or all) of the following event types:
+      - `prefect-cloud.incident.declared`
+      - `prefect-cloud.incident.resolved`
+      - `prefect-cloud.incident.updated.severity`
+
+See [event triggers](/3.0rc/react/understand-events/automations-triggers/#custom-triggers) for more information on custom triggers, and check out your event feed to see the event types emitted by your incidents and other resources (that is, the events that you can react to).
+
+When an incident is declared, any actions you configure such as pausing work pools or sending notifications, execute immediately.
+
+### Manage an incident
+
+During an incident, Prefect Cloud facilitates management through:
+
+- **Monitor active incidents**, view real-time status, severity, and impact
+- **Adjust incident details**, update status, severity, and other relevant information
+- **Collaborate**, add comments and insights; these display with user identifiers and timestamps
+- **Impact assessment**, evaluate how the incident affects ongoing and future workflows
+
+### Resolve and document an incident
+
+Incidents conclude with:
+
+- **Resolution**, update the incident status to reflect resolution steps taken
+- **Documentation**, ensure all actions, comments, and changes are logged for future reference
+
+### Retroactive incident reporting
+
+After an incident's resolution, generate a detailed timeline of the incident: actions taken, updates to severity, and resolution. The report is suitable for compliance and retrospective analysis.

docs/3.0rc/react/state-change-hooks.mdx

@@ -1,16 +1,14 @@
 ---
-title: State change hooks
+title: Example incident state change hooks
 description: Execute code in response to a flow or task entering a given state, without involvement of the Prefect API.
 ---
 
-[State change hooks](/3.0rc/develop/observe-workflows/manage-states/#state-change-hooks) execute code in response to changes in flow or task run states, enabling you to define actions for specific state transitions in a workflow.
-This guide provides examples of real-world use cases.
+[State change hooks](/3.0rc/develop/observe-workflows/manage-states/#state-change-hooks) execute code in response to changes in flow or task run states, enabling you to define actions for specific state transitions in a workflow. Below are two common real-world examples. 
 
-## Example use cases
-
-### Send a notification when a flow run fails
+## Send a notification when a flow run fails
 
 State change hooks enable you to customize messages sent when tasks transition between states, such as sending notifications containing sensitive information when tasks enter a `Failed` state.
+
 Here's an example of running a client-side hook upon a flow run entering a `Failed` state:
 
 ```python
@@ -42,9 +40,9 @@ if __name__ == "__main__":
     failing_flow()
 ```
 
-Note that retries are configured in this example. This means the `on_failure` hook will not run until all `retries` have completed when the flow run enters a `Failed` state.
+Note that retries are configured in this example. This means the `on_failure` hook does not run until all `retries` have completed when the flow run enters a `Failed` state.
 
-### Delete a Cloud Run job when a flow run crashes
+## Delete a Cloud Run job when a flow run crashes
 
 State change hooks help manage infrastructure cleanup in scenarios where tasks spin up individual infrastructure resources independently of Prefect.
 When a flow run crashes, tasks may exit abruptly and result in the potential omission of cleanup logic within the tasks.

docs/3.0rc/react/understand-events/index.mdx

@@ -1,17 +1,12 @@
 ---
 title: Events
-description: Prefect Cloud Event Feed
 ---
 
-An event is a notification of a change. Together, events form a feed of activity recording what's happening across your stack.
+An event is a notification of a change, creating a history of activity in your stack. Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.
 
 Events power several features in Prefect Cloud, including flow run logs, audit logs, and automations.
 
-Events can represent API calls, state transitions, or changes in your execution environment or infrastructure.
-
-Events enable observability into your data stack via the [event feed](/3.0rc/react/understand-events/#event-feed), and the configuration of Prefect's reactivity via [automations](/3.0rc/react/understand-events/automations-triggers/).
-
-![Prefect UI](/3.0rc/img/ui/event-feed.png)
+Events enable observability into your data stack via the [event feed in the UI](#events-in-the-cloud-ui) and the configuration of Prefect's reactivity via [automations](/3.0rc/react/understand-events/automations-triggers/).
 
 ## Event specification
 
@@ -22,16 +17,16 @@ Events adhere to a structured [specification](https://app.prefect.cloud/api/docs
 | Name     | Type   | Required? | Description                                                          |
 | -------- | ------ | --------- | -------------------------------------------------------------------- |
 | occurred | String | yes       | When the event happened                                              |
-| event    | String | yes       | The name of the event that happened                                  |
-| resource | Object | yes       | The primary Resource this event concerns                             |
-| related  | Array  | no        | A list of additional Resources involved in this event                |
-| payload  | Object | no        | An open-ended set of data describing what happened                   |
-| id       | String | yes       | The client-provided identifier of this event                         |
-| follows  | String | no        | The ID of an event that is known to have occurred prior to this one. |
+| event    | String | yes       | Name of the event that happened                                  |
+| resource | Object | yes       | Primary resource this event concerns                             |
+| related  | Array  | no        | List of additional Resources involved in this event                |
+| payload  | Object | no        | Open-ended set of data describing what happened                   |
+| id       | String | yes       | Client-provided identifier of this event                         |
+| follows  | String | no        | ID of an event that is known to have occurred prior to this one |
 
 ## Event grammar
 
-Generally, events have a consistent and informative grammar - an event describes a resource and an action that the resource took or that was taken on that resource. For example, events emitted by Prefect objects take the form of:
+Generally, events have a consistent and informative grammar—an event describes a resource and an action that the resource took or that was taken on that resource. For example, events emitted by Prefect objects take the form of:
 
 ```
 prefect.block.write-method.called
@@ -41,11 +36,11 @@ prefect-cloud.user.logged-in
 
 ## Event sources
 
-Events are automatically emitted by all Prefect objects, including flows, tasks, deployments, work queues, and logs. Prefect-emitted events will contain the `prefect` or `prefect-cloud` resource prefix. Events can also be sent to the Prefect [events API](https://app.prefect.cloud/api/docs#tag/Events) via authenticated http request.
+Events are automatically emitted by all Prefect objects, including flows, tasks, deployments, work queues, and logs. Prefect-emitted events contain the `prefect` or `prefect-cloud` resource prefix. Events can also be sent to the Prefect [events API](https://app.prefect.cloud/api/docs#tag/Events) through an authenticated HTTP request.
 
 ### Emit custom events from Python code
 
-The Prefect Python SDK provides an `emit_event` function that emits an Prefect event when called. The function can be called inside or outside of a task or flow. Running the following code will emit an event to Prefect Cloud, which will validate and ingest the event data.
+The Prefect Python SDK provides an `emit_event` function that emits an Prefect event when called. You can call `emit_event` inside or outside of a task or flow. For example, running this code emits an event to Prefect Cloud, which validates and ingests the event data:
 
 ```python
 from prefect.events import emit_event
@@ -57,14 +52,15 @@ def some_function(name: str="kiki") -> None:
 some_function()
 ```
 
-Note that the `emit_event` arguments shown above are required: `event` represents the name of the event and `resource={"prefect.resource.id": "my_string"}` is the resource id. 
+You must pass `emit_event` two arguments: `event`, the name of the event, and `resource={"prefect.resource.id": "my_string"}`, the resource ID.
+
 To get data into an event for use in an automation action, you can specify a dictionary of values for the `payload` parameter. 
 
-### Emit events via webhooks
+### Emit events through webhooks
 
 Prefect Cloud offers [programmable webhooks](/3.0rc/react/understand-events/webhook-triggers/) to receive HTTP requests from other systems and translate them into events within your workspace.  Webhooks can emit [pre-defined static events](/3.0rc/react/understand-events/webhook-triggers/#static-webhook-events), dynamic events that [use portions of the incoming HTTP request](/3.0rc/react/understand-events/webhook-triggers/#dynamic-webhook-events), or events derived from [CloudEvents](/3.0rc/react/understand-events/webhook-triggers/#accepting-cloudevents).
 
-Events emitted from any source will appear in the event feed, where you can visualize activity in context and configure [automations](/3.0rc/react/understand-events/automations-triggers/) to react to the presence or absence of it in the future. 
+Events emitted from any source appear in the event feed, where you can visualize activity in context and configure [automations](/3.0rc/react/understand-events/automations-triggers/) to react to the presence or absence of events in the future. 
 
 ## Resources
 
@@ -112,10 +108,10 @@ The event feed is the primary place to view, search, and filter events to unders
 
 You can view more information about an event by clicking into it, where you can view the full details of an event's resource, related resources, and its payload.
 
-## Reacting to events
+## Respond to events
 
 From an event page, you can configure an [automation](/3.0rc/react/understand-events/automations-triggers) to trigger on the observation of matching events or a lack of matching events by clicking the automate button in the overflow menu:
 
 ![Automation from event](/3.0rc/img/ui/automation-from-event.png)
 
-The default trigger configuration will fire every time it sees an event with a matching resource identifier. Advanced configuration is possible via [custom triggers](/3.0rc/react/understand-events/automations-triggers/).
+The default trigger configuration fires every time it sees an event with a matching resource identifier. Advanced configuration is possible through [custom triggers](/3.0rc/react/understand-events/automations-triggers/).