Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/apm/advanced-queries.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,22 +14,22 @@ or, to only show transactions that are slower than a specified time threshold.
* Filter by response status code: `context.response.status_code ≥ 400`
* Filter by single user ID: `context.user.id : 12`

When querying in the APM app, you're merely searching and selecting data from fields in Elasticsearch documents.
When querying in the APM app, you're merely searching and selecting data from fields in OpenSearch documents.
Queries entered into the query bar are also added as parameters to the URL,
so it's easy to share a specific query or view with others.

When you type, you can begin to see some of the transaction fields available for filtering:

[role="screenshot"]
image::apm/images/apm-query-bar.png[Example of the Kibana Query bar in APM app in Kibana]
image::apm/images/apm-query-bar.png[Example of the OpenSearchDashboards Query bar in APM app in OpenSearchDashboards]

TIP: Read the {kibana-ref}/kuery-query.html[Kibana Query Language Enhancements] documentation to learn more about the capabilities of the {kib} query language.
TIP: Read the {opensearch-dashboards-ref}/kuery-query.html[OpenSearchDashboards Query Language Enhancements] documentation to learn more about the capabilities of the {osd} query language.

[float]
[[discover-advanced-queries]]
=== Querying in Discover

Alternatively, you can query your APM documents in {kibana-ref}/discover.html[*Discover*].
Alternatively, you can query your APM documents in {opensearch-dashboards-ref}/discover.html[*Discover*].
Querying documents in *Discover* works the same way as querying in the APM app,
and *Discover* supports all of the example APM app queries shown on this page.

Expand Down
8 changes: 4 additions & 4 deletions docs/apm/agent-configuration.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ To get started, choose the services and environments you wish to configure.
The APM app will let you know when your agents have applied your configurations.

[role="screenshot"]
image::apm/images/apm-agent-configuration.png[APM Agent configuration in Kibana]
image::apm/images/apm-agent-configuration.png[APM Agent configuration in OpenSearchDashboards]

[float]
==== Precedence
Expand All @@ -26,10 +26,10 @@ For this reason, it is still essential to set custom default configurations loca
[float]
==== APM Server setup

This feature requires https://www.elastic.co/guide/en/apm/server/master/setup-kibana-endpoint.html[Kibana endpoint configuration] in APM Server.
This feature requires https://www.elastic.co/guide/en/apm/server/master/setup-opensearch-dashboards-endpoint.html[OpenSearchDashboards endpoint configuration] in APM Server.

APM Server acts as a proxy between the agents and Kibana.
Kibana communicates any changed settings to APM Server so that your agents only need to poll APM Server to determine which settings have changed.
APM Server acts as a proxy between the agents and OpenSearchDashboards.
OpenSearchDashboards communicates any changed settings to APM Server so that your agents only need to poll APM Server to determine which settings have changed.

[float]
==== Supported configurations
Expand Down
42 changes: 21 additions & 21 deletions docs/apm/api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Some APM app features are provided via a REST API:

* <<agent-config-api>>
* <<apm-annotation-api>>
* <<kibana-api,Kibana API>>
* <<opensearch-dashboards-api,OpenSearchDashboards API>>

[float]
[[apm-api-example]]
Expand All @@ -19,15 +19,15 @@ Some APM app features are provided via a REST API:
// The following content is reused throughout the API docs
// tag::using-the-APIs[]
Interact with APM APIs using cURL or another API tool.
All APM APIs are Kibana APIs, not Elasticsearch APIs;
because of this, the Kibana dev tools console cannot be used to interact with APM APIs.
All APM APIs are OpenSearchDashboards APIs, not OpenSearch APIs;
because of this, the OpenSearchDashboards dev tools console cannot be used to interact with APM APIs.

For all APM APIs, you must use a request header.
Supported headers are `Authorization`, `kbn-xsrf`, and `Content-Type`.
Supported headers are `Authorization`, `osd-xsrf`, and `Content-Type`.

`Authorization: ApiKey {credentials}`::
Kibana supports token-based authentication with the Elasticsearch API key service.
The API key returned by the {ref}/security-api-create-api-key.html[Elasticsearch create API key API]
OpenSearchDashboards supports token-based authentication with the OpenSearch API key service.
The API key returned by the {ref}/security-api-create-api-key.html[OpenSearch create API key API]
can be used by sending a request with an `Authorization` header that has a value of `ApiKey` followed by the `{credentials}`,
where `{credentials}` is the base64 encoding of `id` and `api_key` joined by a colon.
+
Expand All @@ -36,17 +36,17 @@ Alternatively, you can create a user and use their username and password to auth
Whether using `Authorization: ApiKey {credentials}`, or `-u $USER:$PASSWORD`,
users interacting with APM APIs must have <<apm-app-api-user,sufficient privileges>>.

`kbn-xsrf: true`::
By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:
`osd-xsrf: true`::
By default, you must use `osd-xsrf` for all API calls, except in the following scenarios:

* The API endpoint uses the `GET` or `HEAD` operations
* The path is whitelisted using the <<settings-xsrf-whitelist, `server.xsrf.whitelist`>> setting
* XSRF protections are disabled using the <<settings-xsrf-disableProtection, `server.xsrf.disableProtection`>> setting

`Content-Type: application/json`::
Applicable only when you send a payload in the API request.
{kib} API requests and responses use JSON.
Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
{osd} API requests and responses use JSON.
Typically, if you include the `osd-xsrf` header, you must also include the `Content-Type` header.
// end::using-the-APIs[]

Here's an example CURL request that adds an annotation to the APM app:
Expand All @@ -56,7 +56,7 @@ Here's an example CURL request that adds an annotation to the APM app:
curl -X POST \
http://localhost:5601/api/apm/services/opbeans-java/annotation \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'osd-xsrf: true' \
-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \
-d '{
"@timestamp": "2020-05-11T10:31:30.452Z",
Expand Down Expand Up @@ -425,7 +425,7 @@ The following example creates an annotation for a service named `opbeans-java`.
curl -X POST \
http://localhost:5601/api/apm/services/opbeans-java/annotation \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'osd-xsrf: true' \
-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \
-d '{
"@timestamp": "2020-05-08T10:31:30.452Z",
Expand Down Expand Up @@ -474,26 +474,26 @@ curl -X POST \
*******************************************************
////

[[kibana-api]]
=== Kibana API
[[opensearch-dashboards-api]]
=== OpenSearchDashboards API

In addition to the APM specific API endpoints, Kibana provides its own <<api,REST API>>
which you can use to automate certain aspects of configuring and deploying Kibana.
In addition to the APM specific API endpoints, OpenSearchDashboards provides its own <<api,REST API>>
which you can use to automate certain aspects of configuring and deploying OpenSearchDashboards.
An example is below.

[[api-create-apm-index-pattern]]
==== Customize the APM index pattern

As an alternative to updating <<apm-settings-in-kibana,`apm_oss.indexPattern`>> in your `kibana.yml` configuration file,
you can use Kibana's <<saved-objects-api-update,update object API>> to update the default APM index pattern on the fly.
As an alternative to updating <<apm-settings-in-opensearch-dashboards,`apm_oss.indexPattern`>> in your `opensearch_dashboards.yml` configuration file,
you can use OpenSearchDashboards's <<saved-objects-api-update,update object API>> to update the default APM index pattern on the fly.

The following example sets the default APM app index pattern to `some-other-pattern-*`:

[source,sh]
----
curl -X PUT "localhost:5601/api/saved_objects/index-pattern/apm_static_index_pattern_id" \ <1>
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'osd-xsrf: true' \
-H 'Authorization: Basic ${YOUR_AUTH_TOKEN}' \
-d' {
"attributes": {
Expand Down Expand Up @@ -525,7 +525,7 @@ To view the new APM app index pattern, use the <<saved-objects-api-get,GET objec
[source,sh]
----
curl -X GET "localhost:5601/api/saved_objects/index-pattern/apm_static_index_pattern_id" \ <1>
-H 'kbn-xsrf: true' \
-H 'osd-xsrf: true' \
-H 'Authorization: Basic ${YOUR_AUTH_TOKEN}'
----
<1> `apm_static_index_pattern_id` is the internal, hard-coded ID of the APM index pattern.
Expand All @@ -552,4 +552,4 @@ The API returns the following:

// More examples will go here

More information on Kibana's API is available in <<api,REST API>>.
More information on OpenSearchDashboards's API is available in <<api,REST API>>.
14 changes: 7 additions & 7 deletions docs/apm/apm-alerts.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@

beta::[]

The APM app integrates with Kibana's {kibana-ref}/alerting-getting-started.html[alerting and actions] feature.
The APM app integrates with OpenSearchDashboards's {opensearch-dashboards-ref}/alerting-getting-started.html[alerting and actions] feature.
It provides a set of built-in **actions** and APM specific threshold **alerts** for you to use
and enables central management of all alerts from <<management,Kibana Management>>.
and enables central management of all alerts from <<management,OpenSearchDashboards Management>>.

[role="screenshot"]
image::apm/images/apm-alert.png[Create an alert in the APM app]

For a walkthrough of the alert flyout panel, including detailed information on each configurable property,
see Kibana's <<defining-alerts,defining alerts>>.
see OpenSearchDashboards's <<defining-alerts,defining alerts>>.

The APM app supports four different types of alerts:

Expand Down Expand Up @@ -116,15 +116,15 @@ Select **Save**. The alert has been created and is now active!
[[apm-alert-manage]]
=== Manage alerts and actions

From the APM app, select **Alerts** > **View active alerts** to be taken to the Kibana alerts and actions management page.
From the APM app, select **Alerts** > **View active alerts** to be taken to the OpenSearchDashboards alerts and actions management page.
From this page, you can create, edit, disable, mute, and delete alerts, and create, edit, and disable connectors.

[float]
[[apm-alert-more-info]]
=== More information

See {kibana-ref}/alerting-getting-started.html[alerting and actions] for more information.
See {opensearch-dashboards-ref}/alerting-getting-started.html[alerting and actions] for more information.

NOTE: If you are using an **on-premise** Elastic Stack deployment with security,
communication between Elasticsearch and Kibana must have TLS configured.
More information is in the alerting {kibana-ref}/alerting-getting-started.html#alerting-setup-prerequisites[prerequisites].
communication between OpenSearch and OpenSearchDashboards must have TLS configured.
More information is in the alerting {opensearch-dashboards-ref}/alerting-getting-started.html#alerting-setup-prerequisites[prerequisites].
58 changes: 29 additions & 29 deletions docs/apm/apm-app-users.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
== APM app users and privileges

:beat_default_index_prefix: apm
:beat_kib_app: APM app
:beat_osd_app: APM app
:annotation_index: observability-annotations

++++
Expand All @@ -14,15 +14,15 @@ You can use role-based access control to grant users access to secured
resources. The roles that you set up depend on your organization's security
requirements and the minimum privileges required to use specific features.

{es-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a
{opensearch-security-features} provides {ref}/built-in-roles.html[built-in roles] that grant a
subset of the privileges needed by APM users.
When possible, assign users the built-in roles to minimize the affect of future changes on your security strategy.
If no built-in role is available, you can assign users the privileges needed to accomplish a specific task.
In general, there are three types of privileges you'll work with:

* **Elasticsearch cluster privileges**: Manage the actions a user can perform against your cluster.
* **Elasticsearch index privileges**: Control access to the data in specific indices your cluster.
* **Kibana space privileges**: Grant users write or read access to features and apps within Kibana.
* **OpenSearch cluster privileges**: Manage the actions a user can perform against your cluster.
* **OpenSearch index privileges**: Control access to the data in specific indices your cluster.
* **OpenSearchDashboards space privileges**: Grant users write or read access to features and apps within OpenSearchDashboards.

////
*********************************** ***********************************
Expand All @@ -48,8 +48,8 @@ These users might also need to create and edit dashboards, visualizations, and m
|====
|Role | Purpose

|`kibana_admin`
|Grants access to all features in Kibana.
|`opensearch_dashboards_admin`
|Grants access to all features in OpenSearchDashboards.

|`apm_user`
|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices
Expand All @@ -61,7 +61,7 @@ These users might also need to create and edit dashboards, visualizations, and m
[[apm-app-reader-partial]]
==== Partial APM reader

In some instances, you may wish to restrict certain Kibana apps that a user has access to.
In some instances, you may wish to restrict certain OpenSearchDashboards apps that a user has access to.

. Assign the following built in roles:
+
Expand All @@ -72,16 +72,16 @@ In some instances, you may wish to restrict certain Kibana apps that a user has
|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices
|====

. Assign space privileges to any Kibana space that the user needs access to.
. Assign space privileges to any OpenSearchDashboards space that the user needs access to.
Here are two examples:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
| `Read` or `All` on the {beat_kib_app}
| Allow the use of the the {beat_kib_app}
| `Read` or `All` on the {beat_osd_app}
| Allow the use of the the {beat_osd_app}

| Spaces
| `Read` or `All` on Dashboards and Discover
Expand Down Expand Up @@ -112,7 +112,7 @@ Here are two examples:

NOTE: By default, the `apm_user` built-in role provides access to Observability annotations.
You only need to create an annotation user if the default annotation index
defined in <<apm-settings-kb,`xpack.observability.annotations.index`>> has been customized.
defined in <<apm-settings-osd,`xpack.observability.annotations.index`>> has been customized.

[[apm-app-annotation-user]]
==== Annotation user
Expand All @@ -136,7 +136,7 @@ and assign the following privileges:
|====
+
^1^ +\{ANNOTATION_INDEX\}+ should be the index name you've defined in
<<apm-settings-kb,`xpack.observability.annotations.index`>>.
<<apm-settings-osd,`xpack.observability.annotations.index`>>.

. Assign the `annotation_user` created previously, and the built-in roles necessary to create
a <<apm-app-reader-full,full>> or <<apm-app-reader-partial,partial>> APM reader to any users that need to view annotations in the APM app
Expand Down Expand Up @@ -173,15 +173,15 @@ Central configuration users need to be able to view, create, update, and delete
|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices
|====

. Assign the following Kibana space privileges:
. Assign the following OpenSearchDashboards space privileges:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
|`All` on {beat_kib_app}
|Allow full use of the {beat_kib_app}
|`All` on {beat_osd_app}
|Allow full use of the {beat_osd_app}
|====

[[apm-app-central-config-reader]]
Expand All @@ -199,15 +199,15 @@ but not create, update, or delete them.
|Grants the privileges required for APM users on +{beat_default_index_prefix}*+ indices
|====

. Assign the following Kibana space privileges:
. Assign the following OpenSearchDashboards space privileges:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
|`read` on the {beat_kib_app}
|Allow read access to the {beat_kib_app}
|`read` on the {beat_osd_app}
|Allow read access to the {beat_osd_app}
|====

[[apm-app-central-config-api]]
Expand All @@ -232,31 +232,31 @@ See <<apm-app-api-user>>.

Users can list, search, create, update, and delete central configurations via the APM app API.

. Assign the following Kibana space privileges:
. Assign the following OpenSearchDashboards space privileges:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
|`all` on the {beat_kib_app}
|Allow all access to the {beat_kib_app}
|`all` on the {beat_osd_app}
|Allow all access to the {beat_osd_app}
|====

[[apm-app-api-config-reader]]
==== Central configuration API reader

Sometimes a user only needs to list and search central configurations via the APM app API.

. Assign the following Kibana space privileges:
. Assign the following OpenSearchDashboards space privileges:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
|`read` on the {beat_kib_app}
|Allow read access to the {beat_kib_app}
|`read` on the {beat_osd_app}
|Allow read access to the {beat_osd_app}
|====

[[apm-app-api-annotation-manager]]
Expand Down Expand Up @@ -289,16 +289,16 @@ and assign the following privileges:
|====

. Assign the `annotation_role` created previously,
and the following Kibana space privileges to any annotation API users:
and the following OpenSearchDashboards space privileges to any annotation API users:
+
[options="header"]
|====
|Type | Privilege | Purpose

| Spaces
|`all` on the {beat_kib_app}
|Allow all access to the {beat_kib_app}
|`all` on the {beat_osd_app}
|Allow all access to the {beat_osd_app}
|====

//LEARN MORE
//Learn more about <<kibana-feature-privileges,feature privileges>>.
//Learn more about <<opensearch-dashboards-feature-privileges,feature privileges>>.
Loading