# event_stream capabilities allow components to subscribe to specific events that
occur during the various stages of the [component lifecycle](https://fuchsia.dev/docs/concepts/components/v2/lifecycle).
This includes information about component state changes as well as capability
routing.

For a complete list of supported events and their descriptions, see the
[`fuchsia.component.EventType`](https://fuchsia.googlesource.com/fuchsia/+/refs/changes/44/656544/21/sdk/fidl/fuchsia.sys2/events.fidl#21) reference documentation. See [RFC-121](https://fuchsia.dev/docs/contribute/governance/rfcs/0121_component_events)
for the original RFC for event_stream capabilities.

## Providing event_stream capabilities

event_stream capabilities always originate from component manager. They are
provided to components from AboveRoot. Individual components cannot declare
events in their manifest `capabilities`, nor can they be used `from:
"framework"`

Each event_stream capability has an optional `scope` which determines the
subtree of events that a connecting client would receive. `scope` may be either
a single sub-tree or refer to multiple children.

## Routing event_stream capabilities

Components can [offer](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/event#offer) event_stream capabilities that they receive from
their parent to other components. event_stream capabilities cannot be exposed.

For more details on how the framework routes component capabilities, see
[capability routing](https://fuchsia.dev/docs/concepts/components/v2/capabilities/README#routing).

### Offering

Offering an event capability gives a child component access to that capability:

    {
        offer: [
            {
                event_stream: "started",
                from: "parent",
                scope: ["#child_a"]
                to: [ "#child-a", "#child_b" ],
            },
            {
                event_stream: "stopped",
                from: "parent",
                to: "#child-c",
            }
        ]
    }

Events can only be offered from parent.

## Consuming event_stream capabilities

To consume an event capability, the component must use the `event_stream`
capability. Event streams may be merged by specifying multiple streams in a
single `use`.

To request the capability, add a `use` declaration for it:

    {
        use: [
            { event_stream: ["started", "stopped"] },
        ]
    }

event_streams may only be used `from: "parent"`.

## event_stream routing example

Consider the following example of a component topology:

![event_stream example](https://fuchsia.dev/fuchsia-src/concepts/components/v2/images/example_topology.svg)

Notice the following key aspects of this example:

- `core/archivist`: Receives `started` events for the entire topology through
  an events capability routed from `root`.

      // root.cml
      {
          offer: [
              {
                  event_stream: "started",
                  from: "parent",
                  to: "#core",
              },
          ]
      }

      // core.cml
      {
          offer: [
              {
                  event_stream: "started",
                  from: "parent",
                  to: "#archivist",
              },
              {
                  event_stream: "started",
                  from: "parent",
                  to: "#test_manager",
                  scope: ["#test_manager"],
              }
          ]
      }

      // archivist.cml
      {
          use: [
              { event_stream: "started" },
          ]
      }

- `core/test_manager/archivist`: Receives `started` events for all test
  components through an events capability routed from `test_manager`.

      // test_manager.cml
      {
          offer: [
              {
                  event_stream: "started",
                  from: "parent",
                  to: "#archivist",
              },
              {
                  event_stream: "started",
                  from: "parent",
                  to: "#tests",
                  // Downscopes the event to the tests collection
                  scope: ["#tests"],
              }
          ]
      }

      - The root Archivist gets `started` events for all components in the
      topology from the root, whereas the embedded Archivist only gets events from
      its own test collection.
      NOTE: An event_stream must be routed through the entire topology from the root
      component_manager all the way down to the component that wants to use the event.
      event_streams cannot be used `from: "framework"`, and they are not
      automatically made available in every component's environment.

      // archivist.cml
      {
            use: [
              {
                  event_stream: "started",
                  from: "parent",
              },
          ]
      }

- `core/test_manager/tests:test-12345`: Receives started events for things
  under its collection through an `event_stream` capability routed from
  `test_manager`.

      // test-12345.cml
      {
          use: [
              {
                  event_stream: "started",
                  from: "parent",
              },
          ]
      }

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/concepts/components/v2/capabilities/event.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/concepts/components/v2/capabilities/event.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/concepts/components/v2/capabilities/event.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/concepts/components/v2/capabilities/event.md "Edit the source code of this page")