diff --git a/changelogs/fragments/10722.yml b/changelogs/fragments/10722.yml new file mode 100644 index 000000000000..e57c87ab399e --- /dev/null +++ b/changelogs/fragments/10722.yml @@ -0,0 +1,2 @@ +chore: +- Update Traces README for 3.3 ([#10722](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/10722)) \ No newline at end of file diff --git a/src/plugins/explore/public/application/pages/traces/README.md b/src/plugins/explore/public/application/pages/traces/README.md index 8aaf9bbb274d..6f38d85100b2 100644 --- a/src/plugins/explore/public/application/pages/traces/README.md +++ b/src/plugins/explore/public/application/pages/traces/README.md @@ -4,12 +4,295 @@ ### Query trace data with Discover Traces -Built on the Discover interface and new in 3.3, Discover Traces provides a central interface for querying and exploring traces across large distributed systems. Traces includes a click-to-filter interface, allowing construction of complex PPL queries without having to write them. When a trace requires deeper investigation, a new trace details page reveals individual trace journeys, displaying complete metadata, attributes, and execution context for that specific operation. To activate this functionality, please refer to the step-by-step guide here. +Built on the Discover interface and new in 3.3, Discover Traces provides a centralized interface for querying and exploring traces across large distributed systems. It includes a click-to-filter interface, allowing construction of complex PPL queries without having to write them manually. When a trace requires deeper investigation, a new trace details page reveals individual trace journeys, displaying complete metadata, attributes, and execution context for that specific operation. To activate this functionality, please refer to the step-by-step guide below. + +![PPL Clicks](img/ppl_clicks.gif) ### Explore interactive node-based visualizations with React Flow -3.3 adds the React Flow library to OpenSearch Dashboards core as an experimental feature, providing a standardized framework for interactive node-based visualizations. This integration eliminates version conflicts that occurred when individual plugins bundled copies of the library, providing a consistent user experience. The library is currently being used with the Discover: Traces feature to render service maps that visualize trace spans and service dependencies. Unlike traditional charting libraries, React Flow specializes in workflow and network diagrams, offering drag-and-drop interactions, custom node components, and efficient rendering of thousands of nodes while maintaining accessibility compliance. To activate this functionality, please refer to the step-by-step guide here. +3.3 adds the React Flow library to OpenSearch Dashboards core as an experimental feature, providing a standardized framework for interactive node-based visualizations. This integration eliminates version conflicts that occurred when individual plugins bundled copies of the library, providing a consistent user experience. The library is currently being used with the Discover: Traces feature to render service maps that visualize trace spans and service dependencies. Unlike traditional charting libraries, React Flow specializes in workflow and network diagrams, offering drag-and-drop interactions, custom node components, and efficient rendering of thousands of nodes while maintaining accessibility compliance. + +![React Flow](img/react_flow.gif) + +### Trace to Log correlation + +When both trace and log index patterns are configured with proper correlation objects, OpenSearch Dashboards 3.3 enables seamless navigation between traces and their associated logs. This powerful feature allows developers and operators to quickly jump from a trace span to related log entries, providing complete context for debugging and troubleshooting distributed systems. The correlation is established through common identifiers like trace IDs and span IDs, creating a unified observability experience that bridges the gap between structured traces and detailed log messages. + +![Log Correlation](img/log_correlation.gif) + +## For OpenSearch Dashboards 3.3 Docker and Binary Releases + +Update your `config/opensearch_dashboards.yml` file with the following configuration block enabled: + +```yaml +# =========================================== +# The new OpenSearch Dashboards Experience +# Enable the following four flags together for the new OpenSearch Dashboards discover features +# =========================================== + +# Set the value of this setting to true to enable multiple data source feature. +# data_source.enabled: false + +# Set the value to true to enable workspace feature +# Please note, workspace will not work with multi-tenancy. To enable workspace feature, you need to disable multi-tenancy first with `opensearch_security.multitenancy.enabled: false` +# workspace.enabled: false + +# explore.enabled: false + +# @experimental Set the value to true to enable discover traces +# explore.discoverTraces.enabled: true +``` ## Setup -You should follow the steps from the [Explore setup guide](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/src/plugins/explore/README.md) to create the datasource and workspace first. \ No newline at end of file +You should follow the steps from the [Explore setup guide](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/src/plugins/explore/README.md) to create the data source and workspace first. + +### Create a Trace Index Pattern + +After creating your data source and workspace, you need to create a trace index pattern to enable trace data visualization. + +1. **Get your data source ID** by going to the data source page and clicking on the data source you wish to create the index pattern for. + + ![Data Source](img/data_source.png) + +2. **Copy the data source ID** from the URL after clicking the data source. + + ![Data Source ID](img/data_source_id.png) + +3. **Run the following command** in your terminal to create an index pattern and associate it as a trace signal: + + ```bash + # Replace with your OpenSearch username (e.g., admin) + # Replace with your OpenSearch password + # Replace with your OpenSearch Dashboards port (default: 5601) + # Replace with your workspace ID (found in workspace URL or API) + # Replace with desired ID for the index pattern + # Replace with the index pattern to match (supports wildcards) + # OTel standard of + # Replace with the timestamp field name in your indices + # OTel standard of + # Replace with your data source ID (found in Data sources page) + + curl -u ':' -X POST \ + 'http://localhost:/w//api/saved_objects/index-pattern/' \ + -H 'osd-xsrf: true' \ + -H 'Content-Type: application/json' \ + -d '{ + "attributes": { + "title": "", + "timeFieldName": "", + "signalType": "traces" + }, + "references": [ + { + "type": "data-source", + "name": "dataSource", + "id": "" + } + ] + }' + + # Example + curl -u 'admin:Welcomeuser@123' -X POST \ + 'http://localhost:5601/w/UL8Q0B/api/saved_objects/index-pattern/otel-traces' \ + -H 'osd-xsrf: true' \ + -H 'Content-Type: application/json' \ + -d '{ + "attributes": { + "title": "otel-v1-apm-span*", + "timeFieldName": "endTime", + "signalType": "traces" + }, + "references": [ + { "type": "data-source", "name": "dataSource", "id": "7d5eb970-9d5b-11f0-a487-c138f227c1e6" } + ] + }' + # Output + {"type":"index-pattern","id":"otel-traces","attributes":{"title":"otel-v1-apm-span*","timeFieldName":"endTime","signalType":"traces"},"references":[{"type":"data-source","name":"dataSource","id":"7d5eb970-9d5b-11f0-a487-c138f227c1e6"}],"migrationVersion":{"index-pattern":"7.6.0"},"updated_at":"2025-09-29T21:18:19.911Z","version":"WzExMywxXQ==","workspaces":["UL8Q0B"],"namespaces":["default"]}% + ``` + +4. **Navigate to the Index patterns page** and click on the created index pattern after the command is successfully run. + + ![Index Pattern Page](img/index_pattern_page.png) + +5. **Refresh the field list** by clicking "Refresh field list" on the index pattern page. + + ![Refresh Field List](img/refresh_field_list.png) + +### (Optional) Create a Logs Index Pattern + +If you have logs data that you want to associate with traces, you can create a logs index pattern. + +1. **Run the following command** in your terminal to create an index pattern and associate it as a log signal: + + ```bash + # Replace with your OpenSearch username (e.g., admin) + # Replace with your OpenSearch password + # Replace with your OpenSearch Dashboards port (default: 5601) + # Replace with your workspace ID (found in workspace URL or API) + # Replace with desired ID for the index pattern + # Replace with the index pattern to match (supports wildcards) + # OTel standard of + # Replace with the timestamp field name in your indices + # OTel standard of