diff --git a/_dashboards/visualize/area.md b/_dashboards/visualize/area.md index 0f3b7863d3..5df59579ec 100644 --- a/_dashboards/visualize/area.md +++ b/_dashboards/visualize/area.md @@ -1,6 +1,6 @@ --- layout: default -title: Using area charts +title: Area charts parent: Building data visualizations nav_order: 5 --- diff --git a/_dashboards/visualize/gantt.md b/_dashboards/visualize/gantt.md index 875e35c127..3a9814465a 100644 --- a/_dashboards/visualize/gantt.md +++ b/_dashboards/visualize/gantt.md @@ -1,6 +1,6 @@ --- layout: default -title: Using Gantt charts +title: Gantt charts parent: Building data visualizations nav_order: 30 redirect_from: @@ -18,7 +18,7 @@ To create a Gantt chart, perform the following steps: 1. In the visualizations menu, choose **Create visualization** and **Gantt Chart**. 1. Choose a source for the chart (e.g. some log data). 1. Under **Metrics**, choose **Event**. For log data, each log is an event. -1. Select the **Start Time** and **Duration** fields from your data set. The start time is the timestamp for the beginning of an event. The duration is the amount of time to add to the start time. +1. Select the **Start Time** and **Duration** fields from your dataset. The start time is the timestamp for the beginning of an event. The duration is the amount of time to add to the start time. 1. Under **Results**, choose the number of events to display on the chart. Gantt charts sequence events from earliest to latest based on start time. 1. Choose **Panel settings** to adjust axis labels, time format, and colors. 1. Choose **Update**. diff --git a/_dashboards/visualize/geojson-regionmaps.md b/_dashboards/visualize/geojson-regionmaps.md index 663c4c2f39..aa006e0a24 100644 --- a/_dashboards/visualize/geojson-regionmaps.md +++ b/_dashboards/visualize/geojson-regionmaps.md @@ -1,6 +1,6 @@ --- layout: default -title: Using coordinate and region maps +title: Coordinate and region maps parent: Building data visualizations has_children: true nav_order: 15 @@ -12,7 +12,7 @@ redirect_from: OpenSearch has a standard set of GeoJSON files that provide a vector map with each region map. OpenSearch Dashboards also provides basic map tiles with a standard vector map to create region maps. You can configure the base map tiles using [Web Map Service (WMS)](https://www.ogc.org/standards/wms). For more information, see [Configuring WMS in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/maptiles/). -For air gapped environments, OpenSearch Dashboards provides a self-host maps server. For more information, see [Using the self-host maps server]({{site.url}}{{site.baseurl}}/dashboards/selfhost-maps-server/) +For air-gapped environments, OpenSearch Dashboards provides a self-host maps server. For more information, see [Using the self-host maps server]({{site.url}}{{site.baseurl}}/dashboards/selfhost-maps-server/). While you can't configure a server to support user-defined vector map layers, you can configure your own GeoJSON file and upload it for this purpose. {: .note} @@ -35,7 +35,7 @@ You can use [geojson.io](https://geojson.io/#map=2/20.0/0.0) to extract GeoJSON To create your own custom vector map, upload a JSON file that contains GEO data for your customized regional maps. The JSON file contains vector layers for visualization. -1. Prepare a JSON file to upload. Make sure the file has either a .geojson or .json extension. +1. Prepare a JSON file to upload. Make sure the file has either a `.geojson` or `.json` extension. 1. On the top menu bar, go to **OpenSearch Dashboards > Visualize**. 1. Select the **Create Visualization** button. 1. Select **Region Map**. diff --git a/_dashboards/visualize/maps-stats-api.md b/_dashboards/visualize/maps-stats-api.md index 7939a4e732..f81c7e6ac4 100644 --- a/_dashboards/visualize/maps-stats-api.md +++ b/_dashboards/visualize/maps-stats-api.md @@ -3,7 +3,7 @@ layout: default title: Maps Stats API nav_order: 20 grand_parent: Building data visualizations -parent: Using coordinate and region maps +parent: Coordinate and region maps has_children: false --- diff --git a/_dashboards/visualize/maps.md b/_dashboards/visualize/maps.md index 23e14d41c3..5728fd9092 100644 --- a/_dashboards/visualize/maps.md +++ b/_dashboards/visualize/maps.md @@ -2,7 +2,7 @@ layout: default title: Using maps grand_parent: Building data visualizations -parent: Using coordinate and region maps +parent: Coordinate and region maps nav_order: 10 redirect_from: - /dashboards/maps-plugin/ diff --git a/_dashboards/visualize/maptiles.md b/_dashboards/visualize/maptiles.md index 6b8cc06ef3..6c7afc7462 100644 --- a/_dashboards/visualize/maptiles.md +++ b/_dashboards/visualize/maptiles.md @@ -2,7 +2,7 @@ layout: default title: Configuring a Web Map Service (WMS) grand_parent: Building data visualizations -parent: Using coordinate and region maps +parent: Coordinate and region maps nav_order: 30 redirect_from: - /dashboards/maptiles/ diff --git a/_dashboards/visualize/selfhost-maps-server.md b/_dashboards/visualize/selfhost-maps-server.md index 925c5449fe..439f9b634a 100644 --- a/_dashboards/visualize/selfhost-maps-server.md +++ b/_dashboards/visualize/selfhost-maps-server.md @@ -1,14 +1,14 @@ --- layout: default -title: Using the self-host maps server +title: Using self-hosted map servers grand_parent: Building data visualizations -parent: Using coordinate and region maps +parent: Coordinate and region maps nav_order: 40 redirect_from: - /dashboards/selfhost-maps-server/ --- -# Using the self-host maps server +# Using self-hosted map servers The self-host maps server for OpenSearch Dashboards allows users to access the default maps service in air-gapped environments. OpenSearch-compatible map URLs include a map manifest with map tiles and vectors, the map tiles, and the map vectors. diff --git a/_dashboards/visualize/tsvb.md b/_dashboards/visualize/tsvb.md new file mode 100644 index 0000000000..d845dea58a --- /dev/null +++ b/_dashboards/visualize/tsvb.md @@ -0,0 +1,70 @@ +--- +layout: default +title: TSVB +parent: Building data visualizations +nav_order: 45 +--- + +# TSVB + +The Time-Series Visual Builder (TSVB) is a powerful data visualization tool in OpenSearch Dashboards that allows you to create detailed time-series visualizations. One of its key features is the ability to add annotations or markers at specific time points based on index data. This feature is particularly useful for making connections between multiple indexes and building visualizations that display data over time, such as flight status, delays by type, and more. TSVB currently supports the following visualization types: Area, Line, Metric, Gauge, Markdown, and Data Table. + +## Creating TSVB visualizations from multiple data sources +Introduced 2.14 +{: .label .label-purple } + +Before proceeding, ensure that the following configuration settings are enabled in the `config/opensearch_dasboards.yaml` file: + +```yaml +data_source.enabled: true +vis_type_timeseries.enabled: true +``` +{% include copy-curl.html %} + +Once you have configured [multiple data sources]({{site.url}}{{site.baseurl}}/dashboards/management/multi-data-sources/) in OpenSearch Dashboards, you can use Vega to query those data sources. The following GIF shows the process of creating TSVB visualizations in OpenSearch Dashboards. + +![Process of creating TSVB visualizations in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/dashboards/configure-tsvb.gif) + +**Step 1: Set up and connect data sources** + +Open OpenSearch Dashboards and follow these steps: + +1. Select **Dashboards Management** from the main menu on the left. +2. Select **Data sources** and then select the **Create data source** button. +3. On the **Create data source** page, enter the connection details and endpoint URL. +4. On the **Home** page, select **Add sample data** and then select the **Add data** button for the **Sample web logs** dataset. + +The following GIF shows the steps required to set up and connect a data source. + +![Create data source]({{site.url}}{{site.baseurl}}/images/dashboards/create-datasource.gif) + +**Step 2: Create the visualization** + +Follow these steps to create the visualization: + +1. From the menu on the left, select **Visualize**. +2. On the **Visualizations** page, select **Create Visualization** and then select **TSVB** in the pop-up window. + +**Step 3: Specify data sources** + +After creating a TSVB visualization, data may appear based on your default index pattern. To change the index pattern or configure additional settings, follow these steps: + +1. In the **Create** window, select **Panel options**. +2. Under **Data source**, select the OpenSearch cluster from which to pull data. In this case, choose your newly created data source. +3. Under **Index name**, enter `opensearch_dashboards_sample_data_logs`. +4. Under **Time field**, select `@timestamp`. This setting specifies the time range for rendering the visualization. + +**(Optional) Step 4: Add annotations** + +Annotations are markers that can be added to time-series visualizations. Follow these steps to add annotations: + +1. On the upper-left corner of the page, select **Time Series**. +2. Select the **Annotations** tab and then **Add data source**. +3. In the **Index** name field, specify the appropriate index. In this case, continue using the same index from the previous steps, that is, `opensearch_dashboards_sample_data_logs`. +4. From **Time** field, select `@timestamp`. +5. In the **Fields** field, enter `timestamp`. +6. In the **Row template** field, enter `timestamp`. + +The visualization automatically updates to display your annotations, as shown in the following image. + + TSVB visualization with annotations diff --git a/_dashboards/visualize/vega.md b/_dashboards/visualize/vega.md index 7764d583a6..3a9f6aad4f 100644 --- a/_dashboards/visualize/vega.md +++ b/_dashboards/visualize/vega.md @@ -1,192 +1,137 @@ --- layout: default -title: Using Vega +title: Vega parent: Building data visualizations -nav_order: 45 +nav_order: 50 --- -# Using Vega +# Vega -[Vega](https://vega.github.io/vega/) and [Vega-Lite](https://vega.github.io/vega-lite/) are open-source, declarative language visualization tools that you can use to create custom data visualizations with your OpenSearch data and [Vega Data](https://vega.github.io/vega/docs/data/). These tools are ideal for advanced users comfortable with writing OpenSearch queries directly. Enable the `vis_type_vega` plugin in your `opensearch_dashboards.yml` file to write your [Vega specifications](https://vega.github.io/vega/docs/specification/) in either JSON or [HJSON](https://hjson.github.io/) format or to specify one or more OpenSearch queries within your Vega specification. By default, the plugin is set to `true`. The configuration is shown in the following example. For configuration details, refer to the `vis_type_vega` [README](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/src/plugins/vis_type_vega/README.md). +[Vega](https://vega.github.io/vega/) and [Vega-Lite](https://vega.github.io/vega-lite/) are open-source, declarative language visualization tools that you can use to create custom data visualizations with your OpenSearch data and [Vega data](https://vega.github.io/vega/docs/data/). These tools are ideal for advanced users comfortable with writing OpenSearch queries directly. Enable the `vis_type_vega` plugin in your `opensearch_dashboards.yml` file to write your [Vega specifications](https://vega.github.io/vega/docs/specification/) in either JSON or [HJSON](https://hjson.github.io/) format or to specify one or more OpenSearch queries in your Vega specification. By default, the plugin is set to `true`. + +## Creating Vega visualizations from multiple data sources +Introduced 2.13 +{: .label .label-purple } + +Before proceeding, ensure that the following configuration settings are enabled in the `config/opensearch_dasboards.yaml` file. For configuration details, refer to the `vis_type_vega` [README](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/src/plugins/vis_type_vega/README.md). ``` +data_source.enabled: true vis_type_vega.enabled: true ``` -The following image shows a custom Vega map created in OpenSearch. +After you have configured [multiple data sources]({{site.url}}{{site.baseurl}}/dashboards/management/multi-data-sources/) in OpenSearch Dashboards, you can use Vega to query those data sources. The following GIF shows the process of creating Vega visualizations in OpenSearch Dashboards. -Map created using Vega visualization in OpenSearch Dashboards +![Process of creating Vega visualizations in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/dashboards/configure-vega.gif) -## Querying from multiple data sources +### Step 1: Set up and connect data sources -If you have configured [multiple data sources]({{site.url}}{{site.baseurl}}/dashboards/management/multi-data-sources/) in OpenSearch Dashboards, you can use Vega to query those data sources. Within your Vega specification, add the `data_source_name` field under the `url` property to target a specific data source by name. By default, queries use data from the local cluster. You can assign individual `data_source_name` values to each OpenSearch query within your Vega specification. This allows you to query multiple indexes across different data sources in a single visualization. +Open OpenSearch Dashboards and follow these steps: -The following is an example Vega specification with `Demo US Cluster` as the specified `data_source_name`: +1. Select **Dashboards Management** from the menu on the left. +2. Select **Data sources** and then select the **Create data source** button. +3. On the **Create data source** page, enter the connection details and endpoint URL, as shown in the following GIF. +4. On the **Home page**, select **Add sample data**. Under **Data source**, select your newly created data source, and then select the **Add data button** for the **Sample web logs** dataset. -``` +The following GIF shows the steps required for setting up and connecting a data source. + +![Setting up and connecting data sources with OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/dashboards/Add_datasource.gif) + +### Step 2: Create the visualization + +1. From the menu on the left, select **Visualize**. +2. On the **Visualizations** page, select **Create Visualization** and then select **Vega** in the pop-up window. + +### Step 3: Add the Vega specification + +By default, queries use data from the local cluster. You can assign individual `data_source_name` values to each OpenSearch query in your Vega specification. This allows you to query multiple indexes across different data sources in a single visualization. + +1. Verify that the data source you created is specified under `data_source_name`. Alternatively, in your Vega specification, add the `data_source_name` field under the `url` property to target a specific data source by name. +2. Copy the following Vega specification and then select the **Update** button in the lower-right corner. The visualization should appear. + +```json { - $schema: https://vega.github.io/schema/vega/v5.json - config: { - kibana: {type: "map", latitude: 25, longitude: -70, zoom: 3} - } - data: [ - { - name: table - url: { - index: opensearch_dashboards_sample_data_flights - // This OpenSearchQuery will query from the Demo US Cluster datasource - data_source_name: Demo US Cluster - %context%: true - // Uncomment to enable time filtering - // %timefield%: timestamp - body: { - size: 0 - aggs: { - origins: { - terms: {field: "OriginAirportID", size: 10000} - aggs: { - originLocation: { - top_hits: { - size: 1 - _source: { - includes: ["OriginLocation", "Origin"] - } - } - } - distinations: { - terms: {field: "DestAirportID", size: 10000} - aggs: { - destLocation: { - top_hits: { - size: 1 - _source: { - includes: ["DestLocation"] - } - } - } - } + $schema: https://vega.github.io/schema/vega-lite/v5.json + data: { + url: { + %context%: true + %timefield%: @timestamp + index: opensearch_dashboards_sample_data_logs + data_source_name: YOUR_DATA_SOURCE_TITLE + body: { + aggs: { + 1: { + date_histogram: { + field: @timestamp + fixed_interval: 3h + time_zone: America/Los_Angeles + min_doc_count: 1 + } + aggs: { + 2: { + avg: { + field: bytes } } } } } + size: 0 } - format: {property: "aggregations.origins.buckets"} - transform: [ - { - type: geopoint - projection: projection - fields: [ - originLocation.hits.hits[0]._source.OriginLocation.lon - originLocation.hits.hits[0]._source.OriginLocation.lat - ] - } - ] } - { - name: selectedDatum - on: [ - {trigger: "!selected", remove: true} - {trigger: "selected", insert: "selected"} - ] + format: { + property: aggregations.1.buckets } - ] - signals: [ + } + transform: [ { - name: selected - value: null - on: [ - {events: "@airport:mouseover", update: "datum"} - {events: "@airport:mouseout", update: "null"} - ] + calculate: datum.key + as: timestamp } - ] - scales: [ { - name: airportSize - type: linear - domain: {data: "table", field: "doc_count"} - range: [ - {signal: "zoom*zoom*0.2+1"} - {signal: "zoom*zoom*10+1"} - ] + calculate: datum[2].value + as: bytes } ] - marks: [ + layer: [ { - type: group - from: { - facet: { - name: facetedDatum - data: selectedDatum - field: distinations.buckets - } + mark: { + type: line } - data: [ - { - name: facetDatumElems - source: facetedDatum - transform: [ - { - type: geopoint - projection: projection - fields: [ - destLocation.hits.hits[0]._source.DestLocation.lon - destLocation.hits.hits[0]._source.DestLocation.lat - ] - } - {type: "formula", expr: "{x:parent.x, y:parent.y}", as: "source"} - {type: "formula", expr: "{x:datum.x, y:datum.y}", as: "target"} - {type: "linkpath", shape: "diagonal"} - ] - } - ] - scales: [ - { - name: lineThickness - type: log - clamp: true - range: [1, 8] - } - { - name: lineOpacity - type: log - clamp: true - range: [0.2, 0.8] - } - ] - marks: [ - { - from: {data: "facetDatumElems"} - type: path - interactive: false - encode: { - update: { - path: {field: "path"} - stroke: {value: "black"} - strokeWidth: {scale: "lineThickness", field: "doc_count"} - strokeOpacity: {scale: "lineOpacity", field: "doc_count"} - } - } - } - ] } { - name: airport - type: symbol - from: {data: "table"} - encode: { - update: { - size: {scale: "airportSize", field: "doc_count"} - xc: {signal: "datum.x"} - yc: {signal: "datum.y"} - tooltip: { - signal: "{title: datum.originLocation.hits.hits[0]._source.Origin + ' (' + datum.key + ')', connnections: length(datum.distinations.buckets), flights: datum.doc_count}" - } - } + mark: { + type: circle + tooltip: true } } ] + encoding: { + x: { + field: timestamp + type: temporal + axis: { + title: @timestamp + } + } + y: { + field: bytes + type: quantitative + axis: { + title: Average bytes + } + } + color: { + datum: Average bytes + type: nominal + } + } } ``` {% include copy-curl.html %} + +## Additional resources + +The following resources provide additional information about Vega visualizations in OpenSearch Dashboards: + +- [Improving ease of use in OpenSearch Dashboards with Vega visualizations](https://opensearch.org/blog/Improving-Dashboards-usability-with-Vega/) diff --git a/_dashboards/visualize/visbuilder.md b/_dashboards/visualize/visbuilder.md index de4dfb1666..51ce5b1e46 100644 --- a/_dashboards/visualize/visbuilder.md +++ b/_dashboards/visualize/visbuilder.md @@ -1,13 +1,13 @@ --- layout: default -title: Using VisBuilder +title: VisBuilder parent: Building data visualizations nav_order: 100 redirect_from: - /dashboards/drag-drop-wizard/ --- -# Using VisBuilder +# VisBuilder You can use the VisBuilder visualization type in OpenSearch Dashboards to create data visualizations by using a drag-and-drop gesture. With VisBuilder you have: @@ -19,7 +19,7 @@ You can use the VisBuilder visualization type in OpenSearch Dashboards to create ## Try VisBuilder in the OpenSearch Dashboards playground -If you'd like to try out VisBuilder without installing OpenSearch locally, you can do so in the [Dashboards playground](https://playground.opensearch.org/app/vis-builder#/). +You can try VisBuilder without installing OpenSearch locally by using [OpenSearch Dashboards Playground](https://playground.opensearch.org/app/vis-builder#/). VisBuilder is enabled by default. ## Try VisBuilder locally @@ -37,4 +37,4 @@ Follow these steps to create a new visualization using VisBuilder in your enviro Here’s an example visualization. Your visualization will look different depending on your data and the fields you select. -Visualization generated using sample data \ No newline at end of file +Visualization generated using sample data diff --git a/images/dashboards/Add_datasource.gif b/images/dashboards/Add_datasource.gif new file mode 100644 index 0000000000..789e1a2128 Binary files /dev/null and b/images/dashboards/Add_datasource.gif differ diff --git a/images/dashboards/add-sample-data.gif b/images/dashboards/add-sample-data.gif new file mode 100644 index 0000000000..6e569d704d Binary files /dev/null and b/images/dashboards/add-sample-data.gif differ diff --git a/images/dashboards/configure-tsvb.gif b/images/dashboards/configure-tsvb.gif new file mode 100644 index 0000000000..fc91e9e669 Binary files /dev/null and b/images/dashboards/configure-tsvb.gif differ diff --git a/images/dashboards/configure-vega.gif b/images/dashboards/configure-vega.gif new file mode 100644 index 0000000000..290ad51416 Binary files /dev/null and b/images/dashboards/configure-vega.gif differ diff --git a/images/dashboards/create-datasource.gif b/images/dashboards/create-datasource.gif new file mode 100644 index 0000000000..789e1a2128 Binary files /dev/null and b/images/dashboards/create-datasource.gif differ diff --git a/images/dashboards/make_tsvb.gif b/images/dashboards/make_tsvb.gif new file mode 100644 index 0000000000..fc91e9e669 Binary files /dev/null and b/images/dashboards/make_tsvb.gif differ diff --git a/images/dashboards/tsvb-viz.png b/images/dashboards/tsvb-viz.png new file mode 100644 index 0000000000..efdf12484c Binary files /dev/null and b/images/dashboards/tsvb-viz.png differ diff --git a/images/dashboards/tsvb-with-annotations.png b/images/dashboards/tsvb-with-annotations.png new file mode 100644 index 0000000000..6cb35632b8 Binary files /dev/null and b/images/dashboards/tsvb-with-annotations.png differ diff --git a/images/dashboards/tsvb.png b/images/dashboards/tsvb.png new file mode 100644 index 0000000000..85f55cc3ad Binary files /dev/null and b/images/dashboards/tsvb.png differ diff --git a/images/make_vega.gif b/images/make_vega.gif new file mode 100644 index 0000000000..290ad51416 Binary files /dev/null and b/images/make_vega.gif differ diff --git a/images/vega.png b/images/vega.png new file mode 100644 index 0000000000..ae7ea76c9d Binary files /dev/null and b/images/vega.png differ