Add X-Opaque-Id to search request metadata for query insights

[ansjcy]

Description

Customized and labeling for search queries in top n queries

• Added the ability to send customized labels in a search query.
• Use top n queries service in query insights plugin to read those tags

A simple demo test of the changes:

Steps

• Preparation: First spin up a test cluster, enable security and query insights plugin, and index one document.

curl -X PUT 'localhost:9200/_cluster/settings' -H 'Content-Type: application/json' -d'
{
    "persistent" : {
        "search.insights.top_queries.latency.enabled" : "true",
        "search.insights.top_queries.latency.window_size" : "1m",
        "search.insights.top_queries.latency.top_n_size" : 20
    }
}'

curl -X POST "localhost:9200/my-index-0/_doc/?pretty" -H 'Content-Type: application/json' -d'
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "this is document 1",
  "user": {
    "id": "cyji"
  }
}'

• Do search query on the index with a customized label with X-Opaque-Id

curl -H "X-Opaque-Id: customized-id" -X GET "localhost:9200/my-index-*/_search?size=1000&pretty" -H 'Content-Type: application/json' -d '{}'

• Then query top n queries API, validate the customized label my_tag is there in the top n queries results

✗ curl -X GET "localhost:9200/_insights/top_queries?pretty"
{
  "top_queries" : [
    {
      "timestamp" : 1717620404073,
      "phase_latency_map" : {
        "expand" : 0,
        "query" : 52,
        "fetch" : 2
      },
      "total_shards" : 1,
      "labels" : {
        "X-Opaque-Id" : "customized-id"  // <--------- user provided label 
      },
      "node_id" : "NJZTMuTfTOe-5nyyE1SMtg",
      "source" : "{\"size\":1000}",
      "indices" : [
        "my-index-*"
      ],
      "search_type" : "query_then_fetch",
      "latency" : 3525
    }
  ]
}

Deprecated for the alternative approach: A simple demo test of the changes:

Steps

• Preparation: First spin up a test cluster, enable query insights plugin, and index one document.

curl -X PUT 'localhost:9200/_cluster/settings' -H 'Content-Type: application/json' -d'
{
    "persistent" : {
        "search.insights.top_queries.latency.enabled" : "true",
        "search.insights.top_queries.latency.window_size" : "1m",
        "search.insights.top_queries.latency.top_n_size" : 20
    }
}'

curl -X POST "localhost:9200/my-index-0/_doc/?pretty" -H 'Content-Type: application/json' -d'
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "this is document 1",
  "user": {
    "id": "cyji"
  }
}'

• Do search query on the index with a customized label

curl -X GET "localhost:9200/my-index-*/_search?size=1000&pretty" -H 'Content-Type: application/json' -d '{
  "query" : {
    "term": {
      "user.id": "chenyang"
    }
  },
  "labels": {
    "my_tenant_tag": "customized-tenant-id"
  }
}'

• Then query top n queries API, validate the customized label my_tenant_tag and default labels injected by the default rules are there in the top n queries results

curl -X GET "localhost:9200/_insights/top_queries?pretty"
{
  "top_queries" : [
    {
      "timestamp" : 1714010081376,
      "user_name" : "chenyang",  // <--------- default label 
      "phase_latency_map" : {
        "expand" : 0,
        "query" : 26,
        "fetch" : 1
      },
      "search_type" : "query_then_fetch",
      "source" : "{\"size\":1000,\"query\":{\"term\":{\"user.id\":{\"value\":\"cyji\",\"boost\":1.0}}},\"labels\":{\"my_tenant_tag\":\"customized-tenant-id\",\"user_tenant\":\"t1\",\"user_backend_roles\":[\"br1\",\"b2\"],\"user_name\":\"chenyang\",\"remote_address\":\"1.2.3.4\",\"user_roles\":[\"r1\",\"r2\"]}}",
      "customized_tag" : "customized-tenant-id",  // <--------- User customized label
      "total_shards" : 1,
      "indices" : [
        "my-index-*"
      ],
      "node_id" : "ZeIqCaZtQ3GPDdRwLuXorg",
      "latency" : 38
    }
  ]
}

Detailed Results

Related Issues

#13341

Check List

• New functionality includes testing.
  • All tests pass
• New functionality has been documented.
  • New functionality has javadoc added
• Failing checks are inspected and point to the corresponding known issue(s) (See: Troubleshooting Failing Builds)
• Commits are signed per the DCO using --signoff
• Commit changes are listed out in CHANGELOG.md file (See: Changelog)
• Public documentation issue/PR created

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

❌ Gradle check result for 62b17bf: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[opensearch-trigger-bot]

The backport to 2.x failed:

The process '/usr/bin/git' failed with exit code 128

To backport manually, run these commands in your terminal:

# Navigate to the root of your repository
cd $(git rev-parse --show-toplevel)
# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add ../.worktrees/OpenSearch/backport-2.x 2.x
# Navigate to the new working tree
pushd ../.worktrees/OpenSearch/backport-2.x
# Create a new branch
git switch --create backport/backport-13374-to-2.x
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 9d3cf43e7f06d2011c931cf829439e9fba97f18d
# Push it to GitHub
git push --set-upstream origin backport/backport-13374-to-2.x
# Go back to the original working tree
popd
# Delete the working tree
git worktree remove ../.worktrees/OpenSearch/backport-2.x

Then, create a pull request where the base branch is 2.x and the compare/head branch is backport/backport-13374-to-2.x.