Repository: RasaHQ/rasa
Pull request: Markers docs
**Proposed changes**:
- Closes https://github.com/RasaHQ/rasa/issues/9748

**Status (please check what you already did)**:
- [ ] added some tests for the functionality
- [x] updated the documentation
- [x] updated the changelog (please check [changelog](https://github.com/RasaHQ/rasa/tree/main/changelog) for instructions)
- [ ] reformat files using `black` (please check [Readme](https://github.com/RasaHQ/rasa#code-style) for instructions)


Problem statement:
Success markers: create docs with usage instructions.
Add success markers usage instructions in to the docs. 

**Definition of done:**
- [ ] Docs created, reviewed and merged to main
- [x] Docs references in error messages (add the docs URL constant in error and warning messages as applicable)

Hints from issue discussion:
@aeshky Are we planning for this first version to be experimental?
@TyDunn I thought research features are always released as experimental first, but maybe that's not the case? Do you think it should be experimental? And does this impact the docs (other than having an experimental label)?
@aeshky I think historically they have, but that does not mean we should not have this conversation. We should think about [what the experiment we are running is and what it would take to move it to generally available](https://www.notion.so/rasa/How-might-we-improve-our-experimental-feature-approach-c19b82ee6bbb472fba17e82fa4db24c6).

My impression is that it should start off as experimental. The main impact on the docs is the experimental label, though if we are very happy with our definition of what it would take to move it to generally available, then I might also suggest we include that as well.
The current draft: https://www.notion.so/rasa/Success-failure-markers-docs-2cdf35e7af844ce38034827667a14450

Commit message: removed the word "note"

Patch to review:
diff --git a/docs/docs/markers.mdx b/docs/docs/markers.mdx
new file mode 100644
index 000000000000..5a1cfc69de85
--- /dev/null
+++ b/docs/docs/markers.mdx
@@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
+
+For the `at_least_once` marker we only extract meta information about the first occurrence.
+
+We extract the following meta information:
+
+1. the number of user turns (i.e., the number of `UserUttered` events) preceding the event at which a marker applied
+2. the index of the event at which a marker applied
+
+We output the extracted information in a `.csv` file that contains the following columns:
+
+- sender_id
+- session_idx
+- marker name
+- event_idx (where we index all events in the tracker, starting with index 0)
+- num_preceeding_user_turns
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker_name,event_id,num_preceding_user_turns
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,7,1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,7,1
+```
+
+extracted_markers.csv
+
+### Computed statistics
+
+By default, the command above also computes summary statistics about the meta information gathered. To disable the statistics computation, use the optional flag `--no-stats`.
+
+For each session and each marker, we are interested in the number of user turns which preceded the event at which the marker applied.
+
+Thus we compute the following:
+
+1. **For each session and each marker** we compute "per-session statistics" which include the arithmetic mean, median, minimum, and maximum number of user turns preceding the event  at which the marker applied
+2. **For all sessions and for each marker** we compute
+    1. overall statistics including the arithmetic mean, median, minimum, and maximum number of user turns preceding the event where the respective marker applied in any session
+    2. the number of sessions and the percentage of sessions where each marker applied at least once
+
+The results are stored in tabular format with the suffixes in the files `stats-overall.csv` and `stats-per-session.csv`. You can change the prefix `stats` via the command line.
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker,statistic,value
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,count(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,count(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,count(number of preceding user turns),0
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,max(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,max(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,max(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,mean(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,median(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,median(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,median(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,min(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,min(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,min(number of preceding user turns),nan
+:
+```
+
+stats-per-session.csv
+
+```
+sender_id,session_idx,marker,statistic,value
+all,nan,-,total_number_of_sessions,3
+all,nan,marker_cheer_up,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_cheer_up,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+all,nan,marker_mood_expressed,number_of_sessions_where_marker_applies_at_least_once,2
+all,nan,marker_mood_expressed,percentage_of_sessions_where_marker_applies_at_least_once,66.667
+all,nan,marker_mood_expressed_and_name_provided,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_mood_expressed_and_name_provided,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+:
+```
+
+stats-overall.csv
+
+## Configuring the CLI command
+
+You can configure the marker extraction and statistics computation using the following arguments:
+
+```
+usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
+                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
+                             [--endpoints ENDPOINTS] [-d DOMAIN]
+                             output_filename {first_n,sample,all} ...
+
+positional arguments:
+  output_filename       The filename to write the extracted markers to (CSV format).
+  {first_n,sample,all}
+    first_n             Select trackers sequentially until N are taken.
+    sample              Select trackers by sampling N.
+    all                 Select all trackers.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --config CONFIG       The config file(s) containing marker definitions. This can be a single YAML
+                        file, or a directory that contains several files with marker definitions in
+                        it. The content of these files will be read and merged together. (default:
+                        markers.yml)
+  --no-stats            Do not compute summary statistics. (default: True)
+  --stats-file-prefix [STATS_FILE_PREFIX]
+                        The common file prefix of the files where we write out the compute
+                        statistics. More precisely, the file prefix must consist of a common path
+                        plus a common file prefix, to which suffixes `-overall.csv` and `-per-
+                        session.csv` will be added automatically. (default: stats)
+  --endpoints ENDPOINTS
+                        Configuration file for the tracker store as a yml file. (default:
+                        endpoints.yml)
+  -d DOMAIN, --domain DOMAIN
+                        Domain specification. This can be a single YAML file, or a directory that
+                        contains several files with domain specifications in it. The content of
+                        these files will be read and merged together. (default: domain.yml)
+
+Python Logging Options:
+  -v, --verbose         Be verbose. Sets logging level to INFO. (default: None)
+  -vv, --debug          Print lots of debugging statements. Sets logging level to DEBUG. (default:
+                        None)
+  --quiet               Be quiet! Sets logging level to WARNING. (default: None)usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
+                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
+                             [--endpoints ENDPOINTS] [-d DOMAIN]
+                             output_filename {first_n,sample,all} ...
+
+positional arguments:
+  output_filename       The filename to write the extracted markers to (CSV format).
+  {first_n,sample,all}
+    first_n             Select trackers sequentially until N are taken.
+    sample              Select trackers by sampling N.
+    all                 Select all trackers.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --config CONFIG       The config file(s) containing marker definitions. This can be a single YAML
+                        file, or a directory that contains several files with marker definitions in
+                        it. The content of these files will be read and merged together. (default:
+                        markers.yml)
+  --no-stats            Do not compute summary statistics. (default: True)
+  --stats-file-prefix [STATS_FILE_PREFIX]
+                        The common file prefix of the files where we write out the compute
+                        statistics. More precisely, the file prefix must consist of a common path
+                        plus a common file prefix, to which suffixes `-overall.csv` and `-per-
+                        session.csv` will be added automatically. (default: stats)
+  --endpoints ENDPOINTS
+                        Configuration file for the tracker store as a yml file. (default:
+                        endpoints.yml)
+  -d DOMAIN, --domain DOMAIN
+                        Domain specification. This can be a single YAML file, or a directory that
+                        contains several files with domain specifications in it. The content of
+                        these files will be read and merged together. (default: domain.yml)
+
+Python Logging Options:
+  -v, --verbose         Be verbose. Sets logging level to INFO. (default: None)
+  -vv, --debug          Print lots of debugging statements. Sets logging level to DEBUG. (default:
+                        None)
+  --quiet               Be quiet! Sets logging level to WARNING. (default: None)
+```
\ No newline at end of file


Code review comments:
diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
path: docs/docs/markers.mdx
text: @user1:
Are we sure this command is correct? 

```
> rasa evaluate markers markers.yaml extracted_markers.csv all

usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
                             [--endpoints ENDPOINTS] [-d DOMAIN]
                             output_filename {first_n,sample,all} ...
rasa evaluate markers: error: argument strategy: invalid choice: 'extracted_markers.csv' (choose from 'first_n', 'sample', 'all')
```

Also per `--help`. 

```
rasa evaluate markers --help                                

usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
                             [--endpoints ENDPOINTS] [-d DOMAIN]
                             output_filename {first_n,sample,all}
```

The main positional argument here should be `extracted_markers.csv`, no? That means we shouldn't add `markers.yaml` as a positional argument in this line. 

@user2:
```rasa evaluate markers --config markers.yaml extracted_markers.csv all``` should work (for argparse reasons, and because the strategies are subparsers, optional args on the base command have to be before the strategy). The `--config` flag is needed to use a non-default configuration though, so that should be changed

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
+
+For the `at_least_once` marker we only extract meta information about the first occurrence.
+
+We extract the following meta information:
+
+1. the number of user turns (i.e., the number of `UserUttered` events) preceding the event at which a marker applied
+2. the index of the event at which a marker applied
+
+We output the extracted information in a `.csv` file that contains the following columns:
+
+- sender_id
+- session_idx
+- marker name
+- event_idx (where we index all events in the tracker, starting with index 0)
+- num_preceeding_user_turns
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker_name,event_id,num_preceding_user_turns
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,7,1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,7,1
+```
+
+extracted_markers.csv
+
+### Computed statistics
+
+By default, the command above also computes summary statistics about the meta information gathered. To disable the statistics computation, use the optional flag `--no-stats`.
+
+For each session and each marker, we are interested in the number of user turns which preceded the event at which the marker applied.
+
+Thus we compute the following:
+
+1. **For each session and each marker** we compute "per-session statistics" which include the arithmetic mean, median, minimum, and maximum number of user turns preceding the event  at which the marker applied
+2. **For all sessions and for each marker** we compute
+    1. overall statistics including the arithmetic mean, median, minimum, and maximum number of user turns preceding the event where the respective marker applied in any session
+    2. the number of sessions and the percentage of sessions where each marker applied at least once
+
+The results are stored in tabular format with the suffixes in the files `stats-overall.csv` and `stats-per-session.csv`. You can change the prefix `stats` via the command line.
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker,statistic,value
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,count(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,count(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,count(number of preceding user turns),0
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,max(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,max(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,max(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,mean(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,median(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,median(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,median(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,min(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,min(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,min(number of preceding user turns),nan
+:
+```
+
+stats-per-session.csv
+
+```
+sender_id,session_idx,marker,statistic,value
+all,nan,-,total_number_of_sessions,3
+all,nan,marker_cheer_up,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_cheer_up,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+all,nan,marker_mood_expressed,number_of_sessions_where_marker_applies_at_least_once,2
+all,nan,marker_mood_expressed,percentage_of_sessions_where_marker_applies_at_least_once,66.667
+all,nan,marker_mood_expressed_and_name_provided,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_mood_expressed_and_name_provided,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+:
+```
+
+stats-overall.csv
+
+## Configuring the CLI command
+
+You can configure the marker extraction and statistics computation using the following arguments:
+
+```
+usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
+                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
+                             [--endpoints ENDPOINTS] [-d DOMAIN]
+                             output_filename {first_n,sample,all} ...
+
+positional arguments:
+  output_filename       The filename to write the extracted markers to (CSV format).
+  {first_n,sample,all}
+    first_n             Select trackers sequentially until N are taken.
+    sample              Select trackers by sampling N.
+    all                 Select all trackers.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --config CONFIG       The config file(s) containing marker definitions. This can be a single YAML
path: docs/docs/markers.mdx
text: @user1:
I'm wondering if `--config` is the best name here since it may cause confusion with `config.yaml`. Might it be possible to rename this to `--markers`? 

@author:
We're considering this under this [issue](https://github.com/RasaHQ/rasa/issues/10174). I think it's fine to have different 'configurations' for differen things. I worry we'll end up using 'markers' to mean both the marker config and the marker output 😄

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
+
+For the `at_least_once` marker we only extract meta information about the first occurrence.
+
+We extract the following meta information:
+
+1. the number of user turns (i.e., the number of `UserUttered` events) preceding the event at which a marker applied
+2. the index of the event at which a marker applied
+
+We output the extracted information in a `.csv` file that contains the following columns:
+
+- sender_id
+- session_idx
+- marker name
+- event_idx (where we index all events in the tracker, starting with index 0)
+- num_preceeding_user_turns
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker_name,event_id,num_preceding_user_turns
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,7,1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,7,1
+```
+
+extracted_markers.csv
+
+### Computed statistics
+
+By default, the command above also computes summary statistics about the meta information gathered. To disable the statistics computation, use the optional flag `--no-stats`.
+
+For each session and each marker, we are interested in the number of user turns which preceded the event at which the marker applied.
+
+Thus we compute the following:
+
+1. **For each session and each marker** we compute "per-session statistics" which include the arithmetic mean, median, minimum, and maximum number of user turns preceding the event  at which the marker applied
+2. **For all sessions and for each marker** we compute
+    1. overall statistics including the arithmetic mean, median, minimum, and maximum number of user turns preceding the event where the respective marker applied in any session
+    2. the number of sessions and the percentage of sessions where each marker applied at least once
+
+The results are stored in tabular format with the suffixes in the files `stats-overall.csv` and `stats-per-session.csv`. You can change the prefix `stats` via the command line.
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker,statistic,value
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,count(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,count(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,count(number of preceding user turns),0
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,max(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,max(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,max(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,mean(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,median(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,median(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,median(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,min(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,min(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,min(number of preceding user turns),nan
+:
+```
+
+stats-per-session.csv
+
+```
+sender_id,session_idx,marker,statistic,value
+all,nan,-,total_number_of_sessions,3
+all,nan,marker_cheer_up,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_cheer_up,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+all,nan,marker_mood_expressed,number_of_sessions_where_marker_applies_at_least_once,2
+all,nan,marker_mood_expressed,percentage_of_sessions_where_marker_applies_at_least_once,66.667
+all,nan,marker_mood_expressed_and_name_provided,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_mood_expressed_and_name_provided,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+:
+```
+
+stats-overall.csv
+
+## Configuring the CLI command
+
+You can configure the marker extraction and statistics computation using the following arguments:
+
+```
+usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
+                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
+                             [--endpoints ENDPOINTS] [-d DOMAIN]
+                             output_filename {first_n,sample,all} ...
+
+positional arguments:
+  output_filename       The filename to write the extracted markers to (CSV format).
+  {first_n,sample,all}
+    first_n             Select trackers sequentially until N are taken.
+    sample              Select trackers by sampling N.
+    all                 Select all trackers.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --config CONFIG       The config file(s) containing marker definitions. This can be a single YAML
+                        file, or a directory that contains several files with marker definitions in
+                        it. The content of these files will be read and merged together. (default:
+                        markers.yml)
+  --no-stats            Do not compute summary statistics. (default: True)
+  --stats-file-prefix [STATS_FILE_PREFIX]
+                        The common file prefix of the files where we write out the compute
+                        statistics. More precisely, the file prefix must consist of a common path
+                        plus a common file prefix, to which suffixes `-overall.csv` and `-per-
+                        session.csv` will be added automatically. (default: stats)
+  --endpoints ENDPOINTS
+                        Configuration file for the tracker store as a yml file. (default:
+                        endpoints.yml)
+  -d DOMAIN, --domain DOMAIN
+                        Domain specification. This can be a single YAML file, or a directory that
+                        contains several files with domain specifications in it. The content of
+                        these files will be read and merged together. (default: domain.yml)
+
+Python Logging Options:
+  -v, --verbose         Be verbose. Sets logging level to INFO. (default: None)
+  -vv, --debug          Print lots of debugging statements. Sets logging level to DEBUG. (default:
+                        None)
+  --quiet               Be quiet! Sets logging level to WARNING. (default: None)usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
+                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
+                             [--endpoints ENDPOINTS] [-d DOMAIN]
+                             output_filename {first_n,sample,all} ...
+
+positional arguments:
+  output_filename       The filename to write the extracted markers to (CSV format).
+  {first_n,sample,all}
+    first_n             Select trackers sequentially until N are taken.
+    sample              Select trackers by sampling N.
+    all                 Select all trackers.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --config CONFIG       The config file(s) containing marker definitions. This can be a single YAML
+                        file, or a directory that contains several files with marker definitions in
+                        it. The content of these files will be read and merged together. (default:
+                        markers.yml)
+  --no-stats            Do not compute summary statistics. (default: True)
+  --stats-file-prefix [STATS_FILE_PREFIX]
+                        The common file prefix of the files where we write out the compute
+                        statistics. More precisely, the file prefix must consist of a common path
+                        plus a common file prefix, to which suffixes `-overall.csv` and `-per-
+                        session.csv` will be added automatically. (default: stats)
+  --endpoints ENDPOINTS
+                        Configuration file for the tracker store as a yml file. (default:
+                        endpoints.yml)
+  -d DOMAIN, --domain DOMAIN
+                        Domain specification. This can be a single YAML file, or a directory that
+                        contains several files with domain specifications in it. The content of
+                        these files will be read and merged together. (default: domain.yml)
+
+Python Logging Options:
+  -v, --verbose         Be verbose. Sets logging level to INFO. (default: None)
+  -vv, --debug          Print lots of debugging statements. Sets logging level to DEBUG. (default:
+                        None)
+  --quiet               Be quiet! Sets logging level to WARNING. (default: None)
+```
path: docs/docs/markers.mdx
text: @user1:
Likely a typo: has this been copied twice in the same doc?

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
+
+For the `at_least_once` marker we only extract meta information about the first occurrence.
+
+We extract the following meta information:
+
+1. the number of user turns (i.e., the number of `UserUttered` events) preceding the event at which a marker applied
+2. the index of the event at which a marker applied
+
+We output the extracted information in a `.csv` file that contains the following columns:
+
+- sender_id
+- session_idx
+- marker name
+- event_idx (where we index all events in the tracker, starting with index 0)
+- num_preceeding_user_turns
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker_name,event_id,num_preceding_user_turns
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,7,1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,7,1
+```
+
+extracted_markers.csv
+
+### Computed statistics
+
+By default, the command above also computes summary statistics about the meta information gathered. To disable the statistics computation, use the optional flag `--no-stats`.
+
+For each session and each marker, we are interested in the number of user turns which preceded the event at which the marker applied.
+
+Thus we compute the following:
+
+1. **For each session and each marker** we compute "per-session statistics" which include the arithmetic mean, median, minimum, and maximum number of user turns preceding the event  at which the marker applied
+2. **For all sessions and for each marker** we compute
+    1. overall statistics including the arithmetic mean, median, minimum, and maximum number of user turns preceding the event where the respective marker applied in any session
+    2. the number of sessions and the percentage of sessions where each marker applied at least once
+
+The results are stored in tabular format with the suffixes in the files `stats-overall.csv` and `stats-per-session.csv`. You can change the prefix `stats` via the command line.
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker,statistic,value
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,count(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,count(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,count(number of preceding user turns),0
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,max(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,max(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,max(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,mean(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,median(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,median(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,median(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,min(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,min(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,min(number of preceding user turns),nan
+:
+```
+
+stats-per-session.csv
+
+```
+sender_id,session_idx,marker,statistic,value
+all,nan,-,total_number_of_sessions,3
+all,nan,marker_cheer_up,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_cheer_up,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+all,nan,marker_mood_expressed,number_of_sessions_where_marker_applies_at_least_once,2
+all,nan,marker_mood_expressed,percentage_of_sessions_where_marker_applies_at_least_once,66.667
+all,nan,marker_mood_expressed_and_name_provided,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_mood_expressed_and_name_provided,percentage_of_sessions_where_marker_applies_at_least_once,0.0
path: docs/docs/markers.mdx
text: @user1:
Do we really expect a `nan` as a `session_id` in the csv-file? If they're all `nan`, I'm wondering why the column wasn't omitted. Or is this happening only in a specific setting? 

@user2:
there is a nan because trackers is "all" and `session_idx`s are ints so we shouldn't use "all" to indicate that this is over all sessions easily -- we could move those rows to another file to get rid of the column entirely, use "all" and accept that this column will be loaded as "str" in pandas, ... or use a different value in that column ? 

@author:
I think I just need to explain what the `nan`s mean here. I like having the same column names for both statistics output files. 🤔

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
+
+For the `at_least_once` marker we only extract meta information about the first occurrence.
+
+We extract the following meta information:
+
+1. the number of user turns (i.e., the number of `UserUttered` events) preceding the event at which a marker applied
+2. the index of the event at which a marker applied
+
+We output the extracted information in a `.csv` file that contains the following columns:
+
+- sender_id
+- session_idx
+- marker name
+- event_idx (where we index all events in the tracker, starting with index 0)
+- num_preceeding_user_turns
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker_name,event_id,num_preceding_user_turns
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,7,1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,7,1
+```
+
+extracted_markers.csv
+
+### Computed statistics
+
+By default, the command above also computes summary statistics about the meta information gathered. To disable the statistics computation, use the optional flag `--no-stats`.
+
+For each session and each marker, we are interested in the number of user turns which preceded the event at which the marker applied.
+
+Thus we compute the following:
+
+1. **For each session and each marker** we compute "per-session statistics" which include the arithmetic mean, median, minimum, and maximum number of user turns preceding the event  at which the marker applied
+2. **For all sessions and for each marker** we compute
+    1. overall statistics including the arithmetic mean, median, minimum, and maximum number of user turns preceding the event where the respective marker applied in any session
+    2. the number of sessions and the percentage of sessions where each marker applied at least once
+
+The results are stored in tabular format with the suffixes in the files `stats-overall.csv` and `stats-per-session.csv`. You can change the prefix `stats` via the command line.
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker,statistic,value
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,count(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,count(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,count(number of preceding user turns),0
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,max(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,max(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,max(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,mean(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,median(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,median(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,median(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,min(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,min(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,min(number of preceding user turns),nan
+:
+```
+
+stats-per-session.csv
+
+```
+sender_id,session_idx,marker,statistic,value
+all,nan,-,total_number_of_sessions,3
+all,nan,marker_cheer_up,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_cheer_up,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+all,nan,marker_mood_expressed,number_of_sessions_where_marker_applies_at_least_once,2
+all,nan,marker_mood_expressed,percentage_of_sessions_where_marker_applies_at_least_once,66.667
+all,nan,marker_mood_expressed_and_name_provided,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_mood_expressed_and_name_provided,percentage_of_sessions_where_marker_applies_at_least_once,0.0
path: docs/docs/markers.mdx
text: @user1:
Is the `value` column an int or a float? Seeing two different schemas here is a bit scary. 

@author:
It will depend on the statistic calculated. For example, "the number of" was written as an `int` while "percentage" was written as a `float`. If you read it as a pandas dataframe they will all be treated as floats. I think it's fine as long as the column only contains numbers. What do you think?

@user1:
I worry about the pandas assumption. Yes, pandas will deal with it in an expected way. But what about excel? Spark? Dask? Polars? 

Each library typically has its own little quirk when it comes to casting assumptions and anything that we can proactively do to prevent assumptions from taking over may prevent a small disaster. There's a (pretty darn good) [PyData Amsterdam talk](https://youtu.be/hoaMzebS_l4?t=517) titled "High Performance Data Loss" on the topic. 

@author:
We can create an issue for this and include this in the upcoming marker fixes, as it's more to do with the code than the docs. Thanks for raising it.

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
path: docs/docs/markers.mdx
text: @user1:
This section uses the term "we" frequently and this is a pattern that goes against [the documentation language guidelines](https://www.notion.so/rasa/Tone-and-language-guidelines-cd96f21292b24c1ab7f7457c7973ec69#766266eaf5744ca094bd247409684d28). 

It's about the user, so maybe rephrase it as; 

```
We extract information -> You can extract information
```

@user2:
> extract information about top-level markers which have user-specified names

Is there such a thing as a top-level marker that does not have a user-specified name?

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
+
+For the `at_least_once` marker we only extract meta information about the first occurrence.
+
+We extract the following meta information:
path: docs/docs/markers.mdx
text: @user1:
We -> "You can extract the following meta information"

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
path: docs/docs/markers.mdx
text: @user1:
I think `event` is ambiguous here because it was used to refer to the technical Rasa notion of "event" (`ActionExecuted`, `UserUttered`, etc) at the top, but is referred in a "something that happened at some point in the dialogue" sense here.

@user2:
@author 

> and are used like to variables

You meant "and are used like variable", right?

> for example `action: utter_greet`

I don't understand this example. Is `action` the condition and `utter_greet` the event?

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
path: docs/docs/markers.mdx
text: @user1:
typo in `[...] Makers configuration file, [...]`

@user2:
typo in `you can extract them by running the follow command`

diff_hunk: @@ -0,0 +1,291 @@
+---
+id: markers
+sidebar_label: Markers
+title: Markers
+description: Read more about how to mark points of interest in dialogues using logical expressions.
+abstract: Markers are logical expressions that allow you to describe points in the dialogue that you are interested in. 
+---
+
+:::caution
+
+This feature is currently experimental and might change or be removed in the future. Share your feedback in the forum to help us make it production-ready.
+
+:::
+
+Markers allow you to describe points in a dialogue that you are interested in identifying. In Rasa, a dialogue is represented as a sequence of events, which include bot actions that were executed (`ActionExecuted`), intents that were detected (`UserUttered`), and slots that were set (`SlotSet`). A point of interest in a dialogue can thus be expressed as a logical expression that can be evaluated against the sequence of dialogue events. When this logical expression is met, we "mark" that point in the dialogue for further analysis or inspection.
+
+There are several applications for Markers. For example, they can be used to define your bot's Key Performance Indicators (KPIs), such as dialogue completion or task success. For [Carbon Bot](https://rasa.com/blog/using-conversation-tags-to-measure-carbon-bots-success-rate/) (which helps users offset their carbon emissions from flying) dialogue completion can be defined as "all mandatory slots have been filled", while task success can be defined as "all mandatory slots have been filled and a carbon estimate has been successfully computed". Marking these events allows us to evaluate Carbon Bot's performance by quantifying how often it succeeds and how often it fails.
+
+Markers also allow you to diagnose your dialogues by surfacing important events for further inspection. For example, we might observe that Carbon Bot tends to successfully set the `travel_departure` and `travel_destination` slots, but not the `travel_flight_class`. We can define a marker to quantify how often this scenario occurs and surface relevant dialogues for review as part of [Conversation Driven Development (CDD)](https://rasa.com/blog/conversation-driven-development-a-better-approach-to-building-ai-assistants/).
+
+Markers are defined using a simple `yaml` syntax. For example, here are markers that define dialogue completion and task success for Carbon Bot:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+marker_task_success:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - slot_was_set: travel_flight_class
+        - action: provide_carbon_estimate
+```
+
+And here is a marker for surfacing dialogues where all mandatory slots are set except `travel_flight_class`:
+
+```yaml
+marker_dialogue_completion:
+    and:
+        - slot_was_set: travel_departure
+        - slot_was_set: travel_destination
+        - not:
+            slot_was_set: travel_flight_class
+```
+
+## Defining Markers
+
+To describe the events that we're interested in, we provide `conditions` and `operators`.
+
+Conditions are simple expressions that describe an event, and are used like to variables in a logical expression, for example `action: utter_greet`. Operators allow you to combine conditions or sub-marker definitions which include nested operators and conditions.
+
+### Conditions
+
+We support the following conditions:
+
+- `action`: the specified bot action was executed.
+- `intent`: the specified user intent was detected.
+- `slot_was_set`: the specified slot was set.
+
+We also support their negated forms:
+
+- `not_action`: the event is not an `ActionExecuted` with the specified action.
+- `not_intent`: the event is not a `UserUttered` with the specified intent.
+- `slot_was_not_set`: the specified slot has not been set.
+
+### Operators
+
+To combine conditions, we provide the following operators:
+
+- `and`: all sub-conditions applied.
+- `or`: any of the sub-conditions applied.
+- `not`: the sub-condition did not apply. `not` can have only 1 condition.
+- `seq`: the list of sub-conditions applied in the specified order with any number of events occurring in-between.
+- `at_least_once`: the listed sub-marker definitions occurred at least once. Only the first occurrence will be marked.
+- `never`: the listed sub-marker definitions never occurred.
+
+### Marker Configuration
+
+To define one or more marker, you need to specify a `yaml` configuration file. Here is an example:
+
+```yaml
+marker_name_provided:
+    slot_was_set: name
+marker_mood_expressed:
+    or:
+        - intent: mood_unhappy
+        - intent: mood_great
+marker_cheer_up:
+    seq:
+        - intent: mood_unhappy
+        - action: utter_cheer_up
+marker_bot_challenged:
+    at_least_once:
+        - intent: bot_challenge
+marker_mood_expressed_and_name_provided:
+    and:
+        - slot_was_set: name
+        - or:
+            - intent: mood_unhappy
+            - intent: mood_great
+```
+
+The top level contains unique user-specified names for each marker. This is a dictionary mapping marker names to marker definitions.
+
+Each marker definition can contain an arbitrary combination of `conditions` and `operators` that map to a valid sub-marker definition.
+
+Each `condition` maps a condition tag to a value. For example, in `marker_name_provided`, the tag `slot_was_set` is mapped to the slot `name` which exists in the `domain.yaml` file.
+
+Each `operator` is a dictionary mapping an operator tag (e.g., `and`) to a list of sub markers, which can be conditions or a nested operator-conditions definition (e.g., see `marker_mood_expressed_and_name_provided`).
+
+:::note
+You cannot yet reuse an existing marker name in the definition of another marker.
+
+:::
+
+## Running the Markers script
+
+Markers are extracted from the dialogues already stored in your [tracker store](https://rasa.com/docs/rasa/next/tracker-stores). Once you've created your Marker definitions in the Makers configuration file, you can extract them by running the follow command:
+
+```bash
+rasa evaluate markers markers.yaml extracted_markers.csv all
+```
+
+The argument `all` will cause the script to process all the trackers in your tracker store. To process a subset you can use a different tracker selection strategy, either `first_n` or `sample`. Refer to the CLI usage for details.
+
+Each tracker in the tracker store can contain multiple sessions identified by a `sender_id`. When extracting markers and computing their statistics, each session is considered separately.
+
+
+### Extracted Markers
+
+We extract information about top-level markers which have user-specified names, and extract meta information about all the events where the markers applied.
+
+For the `at_least_once` marker we only extract meta information about the first occurrence.
+
+We extract the following meta information:
+
+1. the number of user turns (i.e., the number of `UserUttered` events) preceding the event at which a marker applied
+2. the index of the event at which a marker applied
+
+We output the extracted information in a `.csv` file that contains the following columns:
+
+- sender_id
+- session_idx
+- marker name
+- event_idx (where we index all events in the tracker, starting with index 0)
+- num_preceeding_user_turns
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker_name,event_id,num_preceding_user_turns
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,7,1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,7,1
+```
+
+extracted_markers.csv
+
+### Computed statistics
+
+By default, the command above also computes summary statistics about the meta information gathered. To disable the statistics computation, use the optional flag `--no-stats`.
+
+For each session and each marker, we are interested in the number of user turns which preceded the event at which the marker applied.
+
+Thus we compute the following:
+
+1. **For each session and each marker** we compute "per-session statistics" which include the arithmetic mean, median, minimum, and maximum number of user turns preceding the event  at which the marker applied
+2. **For all sessions and for each marker** we compute
+    1. overall statistics including the arithmetic mean, median, minimum, and maximum number of user turns preceding the event where the respective marker applied in any session
+    2. the number of sessions and the percentage of sessions where each marker applied at least once
+
+The results are stored in tabular format with the suffixes in the files `stats-overall.csv` and `stats-per-session.csv`. You can change the prefix `stats` via the command line.
+
+Here is a sample output:
+
+```
+sender_id,session_idx,marker,statistic,value
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,count(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,count(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,count(number of preceding user turns),0
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,max(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,max(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,max(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,mean(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,mean(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,median(number of preceding user turns),1.0
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,median(number of preceding user turns),1.0
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,median(number of preceding user turns),nan
+1309ed25d6fa45beb74d0862d37289a5,0,marker_mood_expressed,min(number of preceding user turns),1
+2cf4106e76a041dfb2d4f75bd6ae804b,0,marker_mood_expressed,min(number of preceding user turns),1
+79e7604d2acc442d9f78e00b173786c9,0,marker_mood_expressed,min(number of preceding user turns),nan
+:
+```
+
+stats-per-session.csv
+
+```
+sender_id,session_idx,marker,statistic,value
+all,nan,-,total_number_of_sessions,3
+all,nan,marker_cheer_up,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_cheer_up,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+all,nan,marker_mood_expressed,number_of_sessions_where_marker_applies_at_least_once,2
+all,nan,marker_mood_expressed,percentage_of_sessions_where_marker_applies_at_least_once,66.667
+all,nan,marker_mood_expressed_and_name_provided,number_of_sessions_where_marker_applies_at_least_once,0
+all,nan,marker_mood_expressed_and_name_provided,percentage_of_sessions_where_marker_applies_at_least_once,0.0
+:
+```
+
+stats-overall.csv
+
+## Configuring the CLI command
+
+You can configure the marker extraction and statistics computation using the following arguments:
+
+```
+usage: rasa evaluate markers [-h] [-v] [-vv] [--quiet] [--config CONFIG]
+                             [--no-stats | --stats-file-prefix [STATS_FILE_PREFIX]]
+                             [--endpoints ENDPOINTS] [-d DOMAIN]
+                             output_filename {first_n,sample,all} ...
+
+positional arguments:
+  output_filename       The filename to write the extracted markers to (CSV format).
+  {first_n,sample,all}
+    first_n             Select trackers sequentially until N are taken.
+    sample              Select trackers by sampling N.
path: docs/docs/markers.mdx
text: @user1:
Is there a way to specify `N` for `first_n` and `sample`?

@author:
yes there is a `count` parameter but I don't see that info here. Well spotted. 

@author:
You can get info about `count` and `seed` by typing:
`rasa evaluate markers output.csv sample --help`
However, I've raised an [issue](https://github.com/RasaHQ/rasa/issues/10174) to modify this. It will likely change to:
`rasa evaluate markers <strategy> --help`
where strategy is one of `all`, `sample_n` or `first_n`