Debug session concept and how-to

Author: HeidiSteen

articles/search/cognitive-search-debug-session.md

@@ -1,7 +1,7 @@
 ---
 title: Debug Sessions concepts
 titleSuffix: Azure AI Search
-description: Debug Sessions, accessed through the Azure portal, provides an IDE-like environment where you can identify and fix errors, validate changes, and push changes to skillsets in an enrichment pipeline.
+description: Debug Sessions, accessed through the Azure portal, provides an IDE-like environment where you can identify and fix errors, validate changes, and push changes to skillsets in an Azure AI Search enrichment pipeline.
 
 manager: nitinme
 author: HeidiSteen
@@ -10,73 +10,76 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 07/24/2024
+ms.date: 08/20/2024
 ---
 
 # Debug Sessions in Azure AI Search
 
 Debug Sessions is a visual editor that works with an existing skillset in the Azure portal, exposing the structure and content of a single enriched document as it's produced by an indexer and skillset for the duration of the session. Because you're working with a live document, the session is interactive - you can identify errors, modify and invoke skill execution, and validate the results in real time. If your changes resolve the problem, you can commit them to a published skillset to apply the fixes globally.
 
-This article explains how the editor is organized. Tabs and sections of the editor unpack different layers of the skillset so that you can examine skillset structure, flow, and the content it generates at run time.
+This article explains supported scenarios and how the editor is organized. Tabs and sections of the editor unpack different layers of the skillset so that you can examine skillset structure, flow, and the content it generates at run time.
 
-## How a debug session works
+## Supported scenarios
 
-When you start a session, the search service creates a copy of the skillset, indexer, and a data source containing a single document used to test the skillset. All session state is saved to a new blob container created by the Azure AI Search service in an Azure Storage account that you provide. The name of the generated container has a prefix of `ms-az-cognitive-search-debugsession`. The prefix is required because it mitigates the chance of accidentally exporting session data to another container in your account. 
++ Built-in skills for [AI enrichment](cognitive-search-concept-intro.md) (OCR, image analysis, Entity Recognition, Sentiment Analysis, Keyword Extraction)
 
-A cached copy of the enriched document and skillset is loaded into the visual editor so that you can inspect the content and metadata of the enriched document, with the ability to check each document node and edit any aspect of the skillset definition. Any changes made within the session are cached. Those changes won't affect the published skillset unless you commit them. Committing changes will overwrite the production skillset.
++ Built-in skills for [integrated vectorization](vector-search-integrated-vectorization.md), with data chunking through Text Split, and vectorization through an embedding skill
 
-If the enrichment pipeline doesn't have any errors, a debug session can be used to incrementally enrich a document, test and validate each change before committing the changes.
++ Custom skills used to integrate external processing that you provide.
 
-## AI Enrichments tab > Skill Graph
+Compare the following images for the first two scenarios. Skills for applied AI enrichment can run sequentially or in parallel if there are no dependencies. Output field mappings send enriched or generated content from in-memory data structures to fields in an index.
 
-The visual editor is organized into tabs and panes. This section introduces the components of the visual editor.
+:::image type="content" source="media/cognitive-search-debug/debug-session-flow-applied-ai.png" alt-text="Screenshot of a debug session for OCR and image analysis." lightbox="media/cognitive-search-debug/debug-session-flow-applied-ai.png":::
 
-The **Skill Graph** provides a visual hierarchy of the skillset and its order of execution from top to bottom. Skills that are dependent upon the output of other skills are positioned lower in the graph. Skills at the same level in the hierarchy can execute in parallel. Color coded labels of skills in the graph indicate the types of skills that are being executed in the skillset (TEXT or VISION).
+Skills for integrated vectorization typically include Text Split and embeddings. A Text Split skills chunks a document into pages. Projection mappings control parent-chunk indexing. This skillset skips the parent index and creates an index with just chunked content, using metadata to identify the source of the chunk.
 
-The **Skill Graph** is where you select which skill to debug or enhance. The details pane to the right is where you edit and explore.
+:::image type="content" source="media/cognitive-search-debug/debug-session-flow-integrated-vectorization.png" alt-text="Screenshot of a debug session for integrated vectorization." lightbox="media/cognitive-search-debug/debug-session-flow-integrated-vectorization.png":::
 
-:::image type="content" source="media/cognitive-search-debug/skills-graph.png" alt-text="Screenshot of Skills Graph tab." border="true":::
+## Limitations
 
-### Skill details pane
+Debug sessions work with all generally available [indexer data sources](search-data-sources-gallery.md) and most preview data sources, with the following exceptions:
+
++ SharePoint Online indexer.
 
-Skill details are presented in a tabbed layout and include the following areas:
++ Azure Cosmos DB for MongoDB indexer.
 
-+ **Skill Settings**: a formatted version of the skill definition.
-+ **Skill JSON Editor**: the raw JSON document of the definition.
-+ **Executions**: the data corresponding to each time a skill was executed.
-+ **Errors and warnings**: the messages generated upon session start or refresh.
++ For the Azure Cosmos DB for NoSQL, if a row fails during index and there's no corresponding metadata, the debug session might not pick the correct row.
 
-On Executions or Skill Settings, select the **`</>`** symbol to open the [**Expression Evaluator**](#expression-evaluator) used for viewing and editing the expressions of the skills inputs and outputs.
++ For the SQL API of Azure Cosmos DB, if a partitioned collection was previously non-partitioned, the debug session won't find the document.
 
-Nested input controls in Skill Settings can be used to build complex shapes for [projections](knowledge-store-projection-overview.md), [output field mappings](cognitive-search-output-field-mapping.md) for a complex type field, or an input to a skill. When used with the Expression Evaluator, nested inputs provide an easy test and validate expression builder.
++ For custom skills, a user-assigned managed identity isn't supported for a debug session connection to Azure Storage. As stated in the prerequisites, you can use a system managed identity, or specify a full access connection string that includes a key. For more information, see [Connect a search service to other Azure resources using a managed identity](search-howto-managed-identities-data-sources.md).
 
-### Executions pane
+## How a debug session works
 
-A skill can execute multiple times in a skillset for a single document. For example, the OCR skill executes once for each image extracted from a single document. The Executions pane displays the skill's execution history providing a deeper look into each invocation of the skill. 
+When you start a session, the search service creates a copy of the skillset, indexer, and a data source containing a single document used to test the skillset. All session state is saved to a new blob container created by the Azure AI Search service in an Azure Storage account that you provide. The name of the generated container has a prefix of `ms-az-cognitive-search-debugsession`. The prefix is required because it mitigates the chance of accidentally exporting session data to another container in your account. 
 
-The execution history enables tracking a specific enrichment back to the skill that generated it. Clicking on a skill input navigates to the skill that generated that input, providing a stack-trace like feature. This allows identification of the root cause of a problem that might manifest in a downstream skill. 
+A cached copy of the enriched document and skillset is loaded into the visual editor so that you can inspect the content and metadata of the enriched document, with the ability to check each document node and edit any aspect of the skillset definition. Any changes made within the session are cached. Those changes won't affect the published skillset unless you commit them. Committing changes will overwrite the production skillset.
 
-When you debug an error with a custom skill, there's the option to generate a request for a skill invocation in the execution history.
+If the enrichment pipeline doesn't have any errors, a debug session can be used to incrementally enrich a document, test and validate each change before committing the changes.
 
-## AI Enrichments tab > Enriched Data Structure
+## Debug session layout
 
-The **Enriched Data Structure** pane shows the document's enrichments through the skillset, detailing the context for each enrichment and the originating skill. The Expression Evaluator can also be used to view the contents for each enrichment.
+The visual editor is organized into a surface area showing a progression of operations, starting with document cracking, followed by skills, mappings, and an index.
 
-> :::image type="content" source="media/cognitive-search-debug/enriched-data-structure-display.png" alt-text="Screenshot of Enriched Data Structure tab.":::
+Select any skill or mapping, and a pane opens to side showing relevant information.
 
-## Expression Evaluator
+:::image type="content" source="media/cognitive-search-debug/debug-session-skills-pane.png" lightbox="media/cognitive-search-debug/debug-sessions-skills-pane.png" alt-text="Screenshot showing a skill details pane with drilldown for more information.":::
 
-**Expression Evaluator** shows the executable elements of the kil. It allows for editing the path and testing the results before updating any of the inputs or context for a skill or projection.
+Follow the links to drill further into skills processing. For example, the following screenshot shows the output of the first iteration of the Text Split skill. 
 
-You can open the evaluator from any node or element that shows the **`</>`** symbol, including parts of a dependency graph or nodes in an enrichment tree.
+:::image type="content" source="media/cognitive-search-debug/debug-session-skills-detail-expression-evaluator.png" lightbox="media/cognitive-search-debug/debug-session-skills-detail-expression-evaluator.png" alt-text="Screenshot showing a skill details pane with Expression Evaluator for a given output.":::
 
-Expression Evaluator gives you full interactive access for testing skill context, inputs, and checking outputs.
+### Skill details pane
 
-:::image type="content" source="media/cognitive-search-debug/expression-evaluator.png" alt-text="Screenshot of Expression Evaluator.":::
+Skill details have the following sections.
 
-## Limitations
++ **Iterations**: Show you how many times a skill executes. You can check the inputs and outputs of each one.
++ **Skill Settings**: View or edit the JSON skillset definition.
++ **Errors and warnings**: Shows the errors or warnings specific to this skill.
+
+## Enriched Data Structure
 
-Debug sessions feature doesn't support [SharePoint Online indexer](search-howto-index-sharepoint-online.md).
+The **Enriched Data Structure** pane slides out to the side when you select the blue show or hide arrow symbol. It's human readable representation of what the enriched document contains. Previous screenshots in this article show examples of the enriched data structure.
 
 ## Next steps