diff --git a/_config.yml b/_config.yml index 17118c615e..984dd4ed0a 100644 --- a/_config.yml +++ b/_config.yml @@ -40,6 +40,9 @@ collections: dashboards: permalink: /:collection/:path/ output: true + integrations: + permalink: /:collection/:path/ + output: true tuning-your-cluster: permalink: /:collection/:path/ output: true @@ -112,6 +115,9 @@ just_the_docs: dashboards: name: OpenSearch Dashboards nav_fold: true + integrations: + name: OpenSearch Integrations + nav_fold: true tuning-your-cluster: name: Creating and tuning your cluster nav_fold: true @@ -233,4 +239,4 @@ exclude: - vendor/ruby/ - README.md - .idea - - templates \ No newline at end of file + - templates diff --git a/_integrations/index.md b/_integrations/index.md new file mode 100644 index 0000000000..2fab9abae7 --- /dev/null +++ b/_integrations/index.md @@ -0,0 +1,65 @@ +--- +layout: default +title: OpenSearch Integrations +nav_order: 1 +has_children: false +nav_exclude: true +--- + +# OpenSearch Integrations +Introduced 2.9 +{: .label .label-purple } + +OpenSearch Integrations is a straightforward starting point that OpenSearch and OpenSearch Dashboards users can use to visualize and understand log and metric data for a particular resource, such as NGINX. An _integration_ contains a bundle of metadata, data mappings, and visualizations that make it simple to monitor data from the Integrations resource. + +The OpenSearch Project seeks your feedback on this feature. Let us know on the [OpenSearch forum](https://forum.opensearch.org/) how OpenSearch Integrations works for you or how it can be improved. +{: .label-yellow} + +## Setting up OpenSearch Integrations + +For the latest developer information, including sample code, articles, tutorials, and an API reference, see the following resources: + +- [Integrations repository](https://github.com/opensearch-project/observability/tree/e18cf354fd7720a6d5df6a6de5d53e51a9d43127/integrations) on GitHub +- [Integration Creation Guide](https://github.com/opensearch-project/dashboards-observability/wiki/Integration-Creation-Guide) +- [Integration Documentation Reference](https://github.com/opensearch-project/dashboards-observability/wiki/Integration-Documentation-Reference) +- [Observability plugin for OpenSearch Dashboards](https://github.com/opensearch-project/dashboards-observability/wiki) + +## Integrations schema + +The OpenSearch Integrations schema outlines how to capture, analyze, and visualize data. It includes the selection and configuration of monitoring tools, data collection methods, data storage and retention strategies, and visualization and alerting mechanisms. It follows the [OpenTelemetry Protocol convention](https://github.com/open-telemetry), with OpenSearch [Simple Schema for Observability](https://opensearch.org/docs/latest/observing-your-data/ssfo/) handling the translation from the OpenTelemetry (OTel) schema to the physical index mapping templates. + +Find detailed information about the schema, including schema examples, in the [OpenSearch Observability READ.me file](https://github.com/opensearch-project/opensearch-catalog/blob/main/docs/schema/observability/README.md) and on the [OpenSearch Observability wiki](https://github.com/opensearch-project/dashboards-observability/wiki/OpenSearch-Observability--Home#observability-schema). + +## Get started + +Using the OpenSearch Dashboards interface, you can connect your data, applications, and processes so that you can centrally manage the services you use. All integrations are available in a single view, and OpenSearch Dashboards guides you there from the home page and main menu. + +Learn how to do the following using the OpenSearch Dashboards interface: + +- Access integrations +- View integrations +- Add integrations + +The following image gives you a snapshot of the Integrations interface: + +![Get started with Integrations demo]({{site.url}}{{site.baseurl}}/images/integrations/nginx-integration.gif) + +### Access integrations + +To access integrations, open OpenSearch Dashboards and select **Integrations** from the **Management** menu. The interface displays installed and available integrations. + +## View integrations + +To view an integration, view the dashboard associated with the integration. If the integration doesn't have an associated dashboard, select the desired integration listed under the **Installed** window. View the integration details, such as assets and fields. + +## Add integrations + +If you have not installed any integrations, you'll be prompted to install them from the Integrations interface. Supported integrations are listed in the **Available** window. + +To add an integration, select the desired prepackaged assets. Currently, OpenSearch Integrations has two flows: Add or Try it. The following example uses the Try it flow: + +1. On the **Integrations** page, select **NginX Dashboard**. +2. Select the **Try it** button. _The Try it flow automatically creates a sample index template, adds sample data to the template, and then creates the integration based on that data._ +3. View the asset list and select a dashboard asset. +4. Preview the data visualizations and sample data details. + diff --git a/_observing-your-data/ss4o.md b/_observing-your-data/ss4o.md new file mode 100644 index 0000000000..92fc239e77 --- /dev/null +++ b/_observing-your-data/ss4o.md @@ -0,0 +1,38 @@ +--- +layout: default +title: Simple Schema for Observability +nav_order: 120 +redirect_from: +- /observing-your-data/ssfo/ +--- + +# Simple Schema for Observability +Introduced 2.6 +{: .label .label-purple } + +[Observability]({{site.url}}{{site.baseurl}}/observing-your-data/index/) is a collection of plugins and applications that let you visualize data-driven events by using Piped Processing Language (PPL) to explore and query data stored in OpenSearch. [Simple Schema for Observability](https://github.com/opensearch-project/opensearch-catalog/tree/main/docs/schema/observability), which uses the schema convention `ss4o`, is a standardization for conforming to a common and unified observability schema. With the schema in place, Observability tools can ingest, automatically extract, and aggregate data and create custom dashboards, making it easier to understand the system at a higher level. + +The Simple Schema for Observability is inspired by both [OpenTelemetry](https://opentelemetry.io/docs/) and the Elastic Common Schema (ECS) and uses Amazon Elastic Container Service ([Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_cwe_events.html)) event logs and OpenTelemetry (OTel) metadata. + +Alerts will be supported in a future release. +{: .note } + +## Use cases + +Use cases for the Simple Schema for Observability include: + +* Ingesting observability data from different data types. +* Moving from proprietary configurations that are non-transferable to a consolidated, sharable observability solution that allows users to ingest and display an analysis of any type of telemetry data from any type of provider. +* Conforming dashboards to the schema to align with the data structure so that you can design and organize the dashboard components and visualizations in a way that effectively represents your data. + +Data Prepper conforms to the schema for metrics and will gradually support traces and logs. Data Prepper's [trace mapping]({{site.url}}{{site.baseurl}}/data-prepper/common-use-cases/trace-analytics/) currently provides `service-map` data in a different way than `ss4o` traces. To make the trace mapping compatible with Observability, it will be integrated with the `ss4o` traces schema and will introduce `service-map` as an enriched field. +{: .note } + +## Traces and metrics + +Schema definitions for traces and metrics are defined and supported by the Observability plugin. These schema definitions include: + +- The index structure (mapping). +- The [index naming conventions](https://github.com/opensearch-project/observability/issues/1405). +- A JSON schema for enforcement and validation of the structure. +- The [integration](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/3412) feature for adding preconfigured dashboards and assets. diff --git a/_observing-your-data/ssfo.md b/_observing-your-data/ssfo.md deleted file mode 100644 index 73be83890f..0000000000 --- a/_observing-your-data/ssfo.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -layout: default -title: Simple Schema for Observability -nav_order: 120 ---- - -# Simple Schema for Observability -Introduced 2.6 -{: .label .label-purple } - -OpenSearch 2.6 introduced a standardization for conforming to a common and unified observability schema: Simple Schema for Observability (SSFO). [Observability]({{site.url}}{{site.baseurl}}/observing-your-data/index/) is a collection of plugins and applications that let you visualize data-driven events by using Piped Processing Language (PPL) to explore and query data stored in OpenSearch. - -With the schema in place, Observability tools can ingest, automatically extract, and aggregate data and create custom dashboards, making it easier to understand the system at a higher level. - -SSFO is inspired by both [OpenTelemetry](https://opentelemetry.io/docs/) and the Elastic Common Schema (ECS) and uses Amazon Elastic Container Service ([Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_cwe_events.html)) event logs and OpenTelemetry metadata. - -Alerts will be supported in a future release. -{: .note } - -## Use cases - -Use cases for SSFO include: - -* Ingesting observability data from different data types. -* Moving from proprietary configurations that are non-transferable to a consolidated, sharable observability solution that allows users to ingest and display an analysis of any type of telemetry data from any type of provider. - -Data Prepper conforms to the SSFO schema for metrics and will gradually support traces and logs. - -Data Prepper's [trace mapping]({{site.url}}{{site.baseurl}}/data-prepper/common-use-cases/trace-analytics/) currently provides `service-map` data in a different way than SSFO traces. To make the trace mapping compatible with Observability, it will be integrated with the SSFO traces schema and will introduce `service-map` as an enriched field. -{: .note } - -## Traces and metrics - -Schema definitions for traces and metrics are defined and supported by the Observability plugin. - -These schema definitions include: - -- The index structure (mapping). -- The [index naming conventions](https://github.com/opensearch-project/observability/issues/1405). -- A JSON schema for enforcement and validation of the structure. -- The [integration](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/3412) feature for adding preconfigured dashboards and assets. diff --git a/images/integrations/nginx-integration.gif b/images/integrations/nginx-integration.gif new file mode 100644 index 0000000000..fb8df1d2bf Binary files /dev/null and b/images/integrations/nginx-integration.gif differ