RasaHQ · vcidst · Jul 3, 2023 · Jun 19, 2023 · Jun 19, 2023 · Jun 19, 2023
diff --git a/changelog/12527.doc.md b/changelog/12527.doc.md
@@ -0,0 +1 @@
+Added Documentation for Realtime Markers Section.
diff --git a/docs/docs/command-line-interface.mdx b/docs/docs/command-line-interface.mdx
@@ -30,6 +30,7 @@ import RasaProBanner from "@theme/RasaProBanner";
 |`rasa data validate`      |Checks the domain, NLU and conversation data for inconsistencies.                                                                         |
 |`rasa export`             |Exports conversations from a tracker store to an event broker.                                                                            |
 |`rasa evaluate markers`   |Extracts markers from an existing tracker store.                                                                                          |
+|`rasa marker upload`      |Upload marker configurations to Analytics Data Pipeline                                                                                   |
 |`rasa license`            |Display licensing information.                                                                                                            |
 |`rasa -h`                 |Shows all available commands.                                                                                                             |
 
@@ -661,6 +662,68 @@ Python Logging Options:
   --quiet               Be quiet! Sets logging level to WARNING. (default: None)
 ```
 
+## rasa markers upload
+
+<RasaProLabel />
+
+<RasaProBanner />
+
+:::info New in 3.6
+
+This command is available from Rasa Pro 3.6.0 and requires [Rasa Analytics Data Pipeline](./monitoring/analytics/getting-started-with-analytics.mdx)
+:::
+
+This command applies to [markers](./markers.mdx) and their [real-time processing](./monitoring/analytics/realtime-markers.mdx).
+Running this command validates the marker configuration file against the domain file and uploads the configuration to Analytics Data Pipeline
+
+```
+usage: rasa markers upload [-h] [-v] [-vv] [--quiet]
+                           [--logging-config-file LOGGING_CONFIG_FILE]
+                           [--config CONFIG]
+                           [--rasa-pro-services-url RASA_PRO_SERVICES_URL]
+                           [-d DOMAIN]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --config CONFIG       The marker configuration 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)
+  --rasa-pro-services-url RASA_PRO_SERVICES_URL
+                        The URL of the Rasa Pro Services instance to upload
+                        markers to.Specified URL should not contain a trailing
+                        slash. (default: )
+  -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:
+  You can control level of log messages printed. In addition to these
+  arguments, a more fine grained configuration can be achieved with
+  environment variables. See online documentation for more info.
+
+  -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)
+  --logging-config-file LOGGING_CONFIG_FILE
+                        If set, the name of the logging configuration file
+                        will be set to the given name. (default: None)
+
+Description:
+  The `rasa markers upload` command allows you to upload Markers to the Rasa Pro Services. Markers are custom conversational events that provide additional context for analysis and insights generation. By uploading Markers, you can enable real-time analysis and enhance the performance of your Rasa Assistant.
+
+Examples:
+  Upload Markers to Rasa Pro Services:
+    rasa markers upload --config markers.yml --rasa-pro-services-url https://example.com/rasa-pro -d domain.yml
+
+```
+
 ## rasa license
 
 <RasaProLabel />

diff --git a/docs/docs/markers.mdx b/docs/docs/markers.mdx
@@ -14,6 +14,12 @@ This feature is currently experimental and might change or be removed in the fut
 
 :::
 
+:::danger
+
+In the upcoming release version 3.7 of Rasa Open Source, we’re removing this experimental feature. For documentation on the Markers feature in Rasa Pro, please [click here](./monitoring/analytics/realtime-markers.mdx)
+
+:::
+
 ## Overview
 
 Markers are conditions that allow you to describe and mark points of interest in dialogues for evaluating your bot.
@@ -173,6 +179,12 @@ You cannot reuse an existing marker name in the definition of another marker.
 
 ## Extracting Markers
 
+:::info
+
+Rasa Pro supports real-time processing of Markers, Read more about [Real-Time Markers](monitoring/analytics/realtime-markers.mdx)
+
+:::
+
 Markers are extracted from dialogues already stored in a tracker store. To learn how to store interactions with your bot in a tracker store,
 read the [Tracker Store](./tracker-stores.mdx) page.
 

diff --git a/docs/docs/monitoring/analytics/data-structure-reference.mdx b/docs/docs/monitoring/analytics/data-structure-reference.mdx
@@ -781,6 +781,120 @@ Time of the last update of the slot in this session. The timestamp is a UTC.
 - Type: `DateTime`
 - Example: `2022-06-21 02:15:49.326936`
 
+### rasa_patterns
+
+Patterns are marker definitions that have been received from Rasa. This table is called `patterns`
+to distinguish them from extracted markers which are stored in `rasa_markers` table. It 
+stores the configuration of markers (which can be thought of as a pattern
+of conversational events) along with their metadata.
+
+#### `id` pattern identifier
+
+The unique identifier of the rasa pattern is generated by Analytics.
+
+- Type: `varchar(36)`
+- Example: `bd074dc7-e745-4db6-86d0-75b0af7bc067`
+
+#### `name` pattern name
+
+Name of the pattern
+
+- Type: `varchar()`
+- Example: `registration success`
+
+#### `description` pattern description
+
+Description of the pattern
+
+- Type: `varchar()`
+- Example: `This marker identifies successful account registration in the chat`
+
+#### `config` pattern configuration
+
+Pattern configuration dictionary stored as an escaped string
+
+- Type: `varchar()`
+- Example: `"{'or': [{'intent': 'mood_unhappy'},{'intent': 'mood_great'}]}"`
+
+#### `is_active` soft-delete flag
+
+Only patterns with `is_active==True` are processed during real-time analysis
+
+- Type: `boolean`
+
+#### `created_at` creation date time
+
+Time of creation of this pattern. The timestamp is a UTC.
+
+- Type: `DateTime`
+- Example: `2022-06-21 02:15:49.326936`
+
+#### `updated_at` update date time
+
+Time of the last update of the pattern in this session. The timestamp is a UTC.
+
+- Type: `DateTime`
+- Example: `2022-06-21 02:15:49.326936`
+
+### rasa_markers
+
+Markers are the extracted markers from the conversations. Each row in this table corresponds
+to a marker along with details of the pattern, sender, session and the event
+
+#### `id` marker identifier
+
+The unique identifier of the extracted rasa marker is generated by Analytics.
+
+- Type: `varchar(36)`
+- Example: `bd074dc7-e745-4db6-86d0-75b0af7bc067`
+
+#### `pattern_id` pattern which was applied in this marker
+
+The unique identifier of the pattern which was applied in this marker. It is
+a foreign key to the [`rasa_patterns.id`](#rasa_patterns) column
+
+- Type: `varchar(36)`
+- Example: `9e4ebded-f232-4cc5-af78-d98daa0c1a53`
+
+#### `sender_id` sender identifier
+
+The unique identifier of the sender whose conversation this marker is part of.
+It is a foreign key to the [`rasa_sender.id`](#rasa_sender) column.
+
+- Type: `varchar(36)`
+- Example: `9e4ebded-f232-4cc5-af78-d98daa0c1a53`
+
+#### `session_id` session identifier
+
+The unique identifier of the session this marker is part of.
+It is a foreign key to the [`rasa_session.id`](#rasa_session) column.
+
+- Type: `varchar(36)`
+- Example: `63b150a6-21a3-4e6c-bb24-5ab6ddc30cf1`
+
+#### `event_id` event identifier
+
+The unique identifier of the event from event broker where this marker was applied.
+Note that a marker can be applied across multiple events, this is the ID of the last event in the sequence.
+
+- Type: `varchar(36)`
+- Example: `63b150a6-21a3-4e6c-bb24-5ab6ddc30cf1`
+
+#### `num_preceding_user_turns` Number of Proeeding User turns
+
+an integer indicating the number of user turns preceding the event at which the marker applied.
+
+- Type: `integer`
+- Example: `4`
+
+#### `created_at` creation date time
+
+Time of creation of this marker. The timestamp is a UTC.
+
+- Type: `DateTime`
+- Example: `2022-06-21 02:15:49.326936`
+
+
 ## Internal Tables
 
 Internal tables are used to store information about the assistant and

diff --git a/docs/docs/monitoring/analytics/realtime-markers.mdx b/docs/docs/monitoring/analytics/realtime-markers.mdx
@@ -0,0 +1,87 @@
+---
+id: realtime-markers
+sidebar_label: Real-Time Markers
+title: Real-Time Analysis of Markers
+description:
+abstract: Process Markers real-time from Rasa
+    Assistants to track metrics like solution and abandonment rates,
+    add metatags to conversations,
+    or filter conversations for Conversation Driven Development
+---
+
+import useBaseUrl from "@docusaurus/useBaseUrl";
+import RasaProLabel from "@theme/RasaProLabel";
+import RasaProBanner from "@theme/RasaProBanner";
+import { Grid } from "@theme/Grid";
+
+<RasaProLabel />
+
+:::info Available in Rasa Pro from 3.6.0
+:::
+
+<RasaProBanner />
+
+In Rasa Pro, [Markers](../../markers.mdx) is a powerful feature that allows
+you to track and extract custom conversational events. With the Analytics
+Data Pipeline, you can now process these Markers in real-time, enabling
+you to gain valuable insights and enhance the performance of your Rasa
+Assistant. In this guide, we'll explore how to leverage real-time
+analysis of Markers to track solution rate and abandonment in your conversations.
+
+## Defining Markers
+
+Please consult the [Markers](../../markers.mdx/#defining-markers) section of Rasa documentation
+for details about defining Markers.
+
+## Enable Real-time Processing
+
+To enable real-time analysis of Markers in your Rasa project, you need to
+upload the markers to Analytics Data Pipeline with the `rasa markers upload`
+command. This command uploads the marker configuration YAML and starts the
+processing of Markers in the Analytics Data Pipeline. To get started,
+make sure you have the latest version of Rasa installed. Then, open your command line
+interface and navigate to your Rasa project directory. Run the following command:
+
+```
+rasa markers upload --config=<path-to-config-file> -d=<path-to-domain-file> -rasa-pro-services-url=<url>
+```
+
+By default, this command validates the marker configuration file against
+your bot's domain.yml file. To specify a different domain file, use the
+optional `-d` argument.
+
+This command should be run whenever there is a change in the marker
+configuration file. The changes might include addition of new markers,
+changing an existing marker or removing an existing marker.
+
+:::note
+
+This command **uploads** the marker configurations to the data pipeline. The pipeline assumes the configuration
+file is the source of truth and only processes the markers defined in it. If you remove a marker from this file,
+and run this command, then the processing for that marker is stopped.
+
+:::
+
+### Configuring the CLI command
+
+Visit our [CLI page](./command-line-interface.mdx#rasa-marker-upload)
+for more information about the command line arguments available.
+
+## How are Markers processed?
+
+Once the marker definitions are uploaded to the Analytics Data Pipeline, they
+are stored in the `rasa_patterns` table. As the Kafka Consumer starts receiving events
+from the Rasa Assistant, it starts analyzing them for markers. The Pipeline 
+processes all the events from the Kafka Event Broker and identifies points of 
+interests in the conversation that matches the marker. The extracted markers are stored
+in the data warehouse.
+
+The evaluation of Markers in the Pipeline is similar to the `rasa evaluate markers`
+command which can be used to process markers from the conversations in Tracker Store.
+Read more about it [here](../../markers.mdx/#extracting-markers)
+
+Extracted markers are added to the `rasa_markers` table in the data warehouse
+immediately once they are processed. There might also be instances where
+a marker is applied several times in a conversation. Check out the
+[Data Structure Reference](data-structure-reference.mdx/#rasa-markers) page for the
+database schema of relevant tables.
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -87,6 +87,7 @@ module.exports = {
                     collapsed: true,
                     items: [
                         'monitoring/analytics/getting-started-with-analytics',
+                        'monitoring/analytics/realtime-markers',
                         'monitoring/analytics/example-queries',
                         'monitoring/analytics/data-structure-reference',
                     ],