forked from containers/kubernetes-mcp-server
-
Notifications
You must be signed in to change notification settings - Fork 54
RHOBS-1607: Bump rhobs/obs-mcp to v0.4.0 #341
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
slashpai
wants to merge
3
commits into
openshift:main
Choose a base branch
from
slashpai:bump-obs-mcp
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,176 @@ | ||
| # Logs Toolset (`logs`) | ||
|
|
||
| This toolset provides tools for querying [Grafana Loki](https://grafana.com/oss/loki/) using LogQL and the Loki HTTP API. | ||
| It is implemented by the [`rhobs/obs-mcp`](https://github.com/rhobs/obs-mcp) package and registered into the openshift-mcp-server as the `logs` toolset. | ||
|
|
||
| For Prometheus and Alertmanager MCP tools, see the [metrics toolset guide](./metrics.md). | ||
| For Grafana Tempo and TraceQL (`traces` toolset), see the [tracing toolset guide](./tracing.md). | ||
| For OpenTelemetry Collector configuration assistance (`otelcol` toolset), see the [otelcol toolset guide](./otelcol.md). | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Call **`loki_list_instances`** first to discover `LokiStack` instances, namespaces, multitenancy, and tenant names. | ||
| 2. Use **`loki_label_names`** (and optionally **`loki_label_values`**) to learn which labels exist before writing LogQL queries. | ||
| 3. Run **`loki_query_range`** with a LogQL query to retrieve matching log streams and lines. | ||
|
|
||
| ## Tools | ||
|
|
||
| ### loki_list_instances | ||
|
|
||
| **Discovery entry point.** Lists LokiStack instances visible in the Kubernetes API. | ||
|
|
||
| **Parameters:** none. | ||
|
|
||
| **Output:** JSON per instance includes `lokiNamespace`, `lokiName`, `status`, and resolved `url`. Use `lokiNamespace`, `lokiName`, and `tenant` as parameters on other Loki tools. | ||
|
|
||
| --- | ||
|
|
||
| ### loki_label_names | ||
|
|
||
| List available Loki label names for a time range. Use this before writing LogQL queries to discover which labels are indexed. | ||
|
|
||
| **Parameters:** | ||
| - `lokiNamespace` (string, optional) — Kubernetes namespace of the LokiStack (from `loki_list_instances`) | ||
| - `lokiName` (string, optional) — Name of the LokiStack (from `loki_list_instances`) | ||
| - `tenant` (string, optional) — Loki tenant ID; for LokiStack gateway modes (e.g. openshift-network) use `network` | ||
| - `start` (string, optional) — Start time (RFC3339, Unix timestamp, `NOW`, or relative like `NOW-1h`) | ||
| - `end` (string, optional) — End time (RFC3339, Unix timestamp, `NOW`, or relative) | ||
|
|
||
| --- | ||
|
|
||
| ### loki_label_values | ||
|
|
||
| List possible values for a Loki label key. Use this to build precise label matchers in LogQL. | ||
|
|
||
| **Parameters:** | ||
| - `label` (string, required) — Label key to inspect (e.g. `namespace`, `pod`, `container`, `SrcK8S_Namespace`) | ||
| - `lokiNamespace`, `lokiName`, `tenant`, `start`, `end` — same as `loki_label_names` | ||
|
|
||
| --- | ||
|
|
||
| ### loki_query_range | ||
|
|
||
| Execute a Loki LogQL range query and return matching log streams and lines. | ||
|
|
||
| **Parameters:** | ||
| - `query` (string, required) — LogQL query string (e.g. `{namespace="default"}`) | ||
| - `lokiNamespace` (string, optional) — Kubernetes namespace of the LokiStack | ||
| - `lokiName` (string, optional) — Name of the LokiStack | ||
| - `tenant` (string, optional) — Loki tenant ID | ||
| - `duration` (string, optional) — Lookback duration from now when start/end are omitted (e.g. `5m`, `1h`). Defaults to `15m` | ||
| - `start` (string, optional) — Start time (RFC3339, Unix, `NOW`, or relative) | ||
| - `end` (string, optional) — End time (RFC3339, Unix, `NOW`, or relative) | ||
| - `limit` (number, optional) — Maximum number of log lines to return. Defaults to 100, max 1000 | ||
| - `direction` (string, optional) — Search direction: `backward` (default) or `forward` | ||
|
|
||
| --- | ||
|
|
||
| ## Enable the Toolset | ||
|
|
||
| ### Command line | ||
|
|
||
| ```bash | ||
| kubernetes-mcp-server --toolsets core,logs | ||
| ``` | ||
|
|
||
| ### Configuration file (TOML) | ||
|
|
||
| ```toml | ||
| toolsets = ["core", "logs"] | ||
| ``` | ||
|
|
||
| ### MCP client configuration | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "kubernetes": { | ||
| "command": "npx", | ||
| "args": ["-y", "kubernetes-mcp-server@latest", "--toolsets", "core,logs"] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You can enable **`metrics`**, **`traces`**, and **`logs`** together (same obs-mcp dependency, different toolsets): | ||
|
|
||
| ```toml | ||
| toolsets = ["core", "metrics", "traces", "logs"] | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Configuration | ||
|
|
||
| Optional settings use a **`[toolset_configs.logs]`** section (the key is the toolset name `logs`). | ||
|
|
||
| ```toml | ||
| [toolset_configs.logs] | ||
| # Where to read the bearer token from: "header" (default) or "kubeconfig". | ||
| # Set to "kubeconfig" when running locally (STDIO mode) so the token is read | ||
| # from your kubeconfig session (e.g. after `oc login`). | ||
| auth_mode = "kubeconfig" | ||
|
|
||
| # URL of the Loki API endpoint. | ||
| # Optional — if unset, use LokiStack discovery (loki_list_instances + lokiNamespace/lokiName). | ||
| # Example for a direct Loki endpoint: | ||
| # loki_url = "https://logging-loki-gateway-http.openshift-logging.svc.cluster.local:8080" | ||
| loki_url = "" | ||
|
|
||
| # Skip TLS certificate verification (development only). Default: false | ||
| insecure = false | ||
|
|
||
| # Resolve Loki query URLs via OpenShift Routes instead of in-cluster Services. | ||
| # Default: false | ||
| useRoute = false | ||
| ``` | ||
|
|
||
| ### Configuration reference | ||
|
|
||
| | Option | Type | Default | Description | | ||
| |--------|------|---------|-------------| | ||
| | `auth_mode` | string | `"header"` | Bearer token source: `"header"` or `"kubeconfig"` | | ||
| | `loki_url` | string | — | Loki API endpoint URL (optional; use LokiStack discovery if unset) | | ||
| | `insecure` | bool | `false` | Skip TLS certificate verification | | ||
| | `useRoute` | bool | `false` | Use OpenShift `Route` resources for LokiStack gateway URLs | | ||
|
|
||
| --- | ||
|
|
||
| ## Authentication and TLS | ||
|
|
||
| Bearer token behavior matches the [metrics toolset](./metrics.md) (**Authentication and TLS** section): `auth_mode` chooses header vs kubeconfig, and TLS uses kubeconfig CA data, OpenShift service CA when in-cluster, then the system trust store. Set `insecure = true` only when you cannot install the correct CA (not recommended in production). | ||
|
|
||
| ### Loki URL resolution | ||
|
|
||
| When the `logs` toolset is enabled, the Loki URL is determined in this order: | ||
|
|
||
| 1. `loki_url` in the `[toolset_configs.logs]` config section (if set) | ||
| 2. `LOKI_URL` environment variable | ||
| 3. Default: `http://localhost:3100` (kubeconfig mode only) | ||
|
|
||
| In `header` mode, you can either set `loki_url` **or** use LokiStack discovery (`loki_list_instances` + `lokiNamespace`/`lokiName` arguments on each tool call). | ||
|
|
||
| --- | ||
|
|
||
| ## Instance discovery | ||
|
|
||
| The server lists **`LokiStack`** objects cluster-wide and derives gateway base URLs from each resource. With **`useRoute = true`**, it prefers OpenShift `Route` hosts where available. | ||
|
|
||
| Chosen instances are **validated** against this discovery list before any request is sent, so callers cannot point tools at arbitrary URLs. | ||
|
|
||
| --- | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - **Loki Operator** workloads in the cluster (`LokiStack` CRs) or a standalone Loki endpoint. | ||
| - **RBAC** on the MCP identity to **list** `LokiStack` objects cluster-wide. If **`useRoute`** is enabled, the server also **gets** `Route` resources in each Loki namespace to resolve external hosts. | ||
| - **Bearer token** with permission to reach the resolved Loki API (same patterns as the metrics toolset). | ||
|
|
||
| --- | ||
|
|
||
| ## Related documentation | ||
|
|
||
| - [Metrics toolset guide](./metrics.md) — Prometheus and Alertmanager (`metrics` toolset) | ||
| - [Tracing toolset guide](./tracing.md) — Grafana Tempo and TraceQL (`traces` toolset) | ||
| - [OpenTelemetry Collector toolset guide](./otelcol.md) — Component discovery, schemas, config validation (`otelcol` toolset) | ||
| - [OTEL.md](../OTEL.md) — OpenTelemetry export from this MCP server process (not the same as querying Loki in-cluster) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
23 changes: 23 additions & 0 deletions
23
evals/tasks/observability/logs/loki-backend-reachability.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| kind: Task | ||
| apiVersion: mcpchecker/v1alpha2 | ||
| metadata: | ||
| name: loki-backend-reachability | ||
| difficulty: easy | ||
| parallel: true | ||
| runs: 1 | ||
| labels: | ||
| category: logs | ||
| suite: observability | ||
| toolType: smoke-test | ||
| description: | | ||
| Smoke test that the agent can reach Loki via loki_list_instances and report | ||
| a discovered LokiStack. Run obs-mcp with --toolsets logs (or metrics,traces,logs). | ||
| spec: | ||
| prompt: | ||
| inline: | | ||
| Is the Loki backend reachable? List LokiStack instances and report the | ||
| name, namespace, and URL of any stack you find. | ||
| verify: | ||
| - llmJudge: | ||
| contains: "obs-mcp-loki" | ||
| reason: "Verify the agent discovered the obs-mcp-loki LokiStack from loki_list_instances" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| kind: Task | ||
| apiVersion: mcpchecker/v1alpha2 | ||
| metadata: | ||
| name: loki-label-names | ||
| difficulty: medium | ||
| parallel: true | ||
| runs: 1 | ||
| labels: | ||
| category: logs | ||
| suite: observability | ||
| toolType: exploration | ||
| description: | | ||
| Tests discovery workflow: loki_list_instances then loki_label_names with tenant | ||
| network on the obs-mcp-loki stack (openshift-network mode). | ||
| spec: | ||
| prompt: | ||
| inline: | | ||
| For LokiStack obs-mcp-loki in namespace obs-mcp-loki, tenant network, what | ||
| label names are available for writing LogQL queries? | ||
| verify: | ||
| - llmJudge: | ||
| contains: "SrcK8S_Namespace" | ||
| reason: "NetObserv flow logs expose SrcK8S_Namespace as an indexed Loki label" | ||
| - llmJudge: | ||
| contains: "DstK8S_Namespace" | ||
| reason: "NetObserv flow logs expose DstK8S_Namespace as an indexed Loki label" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| kind: Task | ||
| apiVersion: mcpchecker/v1alpha2 | ||
| metadata: | ||
| name: loki-label-values | ||
| difficulty: medium | ||
| parallel: true | ||
| runs: 1 | ||
| labels: | ||
| category: logs | ||
| suite: observability | ||
| toolType: exploration | ||
| description: | | ||
| Tests loki_label_values for SrcK8S_Namespace on the network tenant. | ||
| spec: | ||
| prompt: | ||
| inline: | | ||
| For LokiStack obs-mcp-loki in namespace obs-mcp-loki with tenant network, | ||
| what values exist for the SrcK8S_Namespace label? | ||
| verify: | ||
| - llmJudge: | ||
| contains: "SrcK8S_Namespace" | ||
| reason: "Verify the agent queried the SrcK8S_Namespace label" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| kind: Task | ||
| apiVersion: mcpchecker/v1alpha2 | ||
| metadata: | ||
| name: loki-list-instances | ||
| difficulty: easy | ||
| parallel: true | ||
| runs: 1 | ||
| labels: | ||
| category: logs | ||
| suite: observability | ||
| toolType: discovery | ||
| description: | | ||
| Tests that the agent calls loki_list_instances before other Loki tools. | ||
| spec: | ||
| prompt: | ||
| inline: | | ||
| Which LokiStack instances are available in this cluster? | ||
| verify: | ||
| - llmJudge: | ||
| contains: "obs-mcp-loki" | ||
| reason: "Verify the agent reported LokiStack instance details" |
27 changes: 27 additions & 0 deletions
27
evals/tasks/observability/logs/loki-query-network-flows.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| kind: Task | ||
| apiVersion: mcpchecker/v1alpha2 | ||
| metadata: | ||
| name: loki-query-network-flows | ||
| difficulty: medium | ||
| parallel: true | ||
| runs: 1 | ||
| labels: | ||
| category: logs | ||
| suite: observability | ||
| toolType: query | ||
| description: | | ||
| Tests loki_query_range with NetObserv flow log labels (SrcK8S_Namespace / | ||
| DstK8S_Namespace) and tenant network—not kubernetes_namespace_name. | ||
| spec: | ||
| prompt: | ||
| inline: | | ||
| Query NetObserv network flow logs from the last hour where the source or | ||
| destination namespace is obs-mcp-loki. Use LokiStack obs-mcp-loki in namespace | ||
| obs-mcp-loki with tenant network. | ||
| verify: | ||
| - llmJudge: | ||
| contains: "SrcK8S_Namespace" | ||
| reason: "Verify the agent used obs-mcp-loki indexed namespace labels in LogQL" | ||
| - llmJudge: | ||
| contains: "network" | ||
| reason: "Verify the agent used tenant network for the openshift-network LokiStack" |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This was non existing doc likely from before obs-mcp toolset