log-analytics — Claude Code skill: log analysis and install
log-analytics is a Claude Code skill that analyzes OpenSearch logs with PPL and Query DSL. It activates for searches into errors, log patterns, rates, and anomalies.
Apache-2.0 131 installs ★ 63 updated 2026-10-24
npx skills add opensearch-project/opensearch-agent-skills --skill log-analytics -a claude-codeWhat log-analytics does
The skill explores log data in OpenSearch. It discovers relevant indices and checks their mappings before building queries with the fields it finds. PPL is the primary query language; Query DSL handles complex aggregations.
A running OpenSearch cluster and uv for helper scripts are required. PPL queries need the OpenSearch SQL plugin. When a cluster endpoint is available, the skill validates queries; without one, it labels them unverified. Before analysis, the agent asks for the cluster endpoint and authentication method.
What it helps with
- find application errors in OpenSearch logs
- track error counts by service over time
- surface rare messages and recurring log patterns
- validate PPL queries against a reachable cluster
Example prompts for the agent
- Find recent application errors in OpenSearch and group them by service.
- Show how the error rate in these logs changed over the selected period.
- Look for recurring patterns and rare messages in the application logs.
How to install log-analytics
1Skills CLI (Vercel)
npx skills add opensearch-project/opensearch-agent-skills --skill log-analytics -a claude-code2Manually: put the files in place
~/.claude/skills/log-analytics/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/log-analytics/
1Skills CLI (Vercel)
npx skills add opensearch-project/opensearch-agent-skills --skill log-analytics -a codex2Manually: put the files in place
.agents/skills/log-analytics/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add opensearch-project/opensearch-agent-skills --skill log-analytics -a cursor2Manually: put the files in place
.cursor/skills/log-analytics/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install opensearch-project/opensearch-agent-skills skills/opensearch-skills/observability/log-analytics2Manually: put the files in place
.github/skills/log-analytics/SKILL.md1Skills CLI (Vercel)
npx skills add opensearch-project/opensearch-agent-skills --skill log-analytics -a gemini-cli2Platform CLI
gemini skills install https://github.com/opensearch-project/opensearch-agent-skills --path skills/opensearch-skills/observability/log-analyticsManually: put the files in place
.devin/skills/log-analytics/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add opensearch-project/opensearch-agent-skills --skill log-analytics -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about log-analytics
How do I install log-analytics in Claude Code?
Run npx skills add opensearch-project/opensearch-agent-skills --skill log-analytics -a claude-code. The skill file is at ~/.claude/skills/log-analytics/SKILL.md.
What does log-analytics do?
It explores OpenSearch logs, identifies relevant indices and fields, then builds PPL or Query DSL queries for investigating errors and log patterns.
What does log-analytics need to run?
It requires a running OpenSearch cluster and uv for helper scripts. PPL queries also require the OpenSearch SQL plugin.
Source text
SKILL.md · Apache-2.0
---
name: log-analytics
description: >
Analyze logs in OpenSearch using PPL and Query DSL. Use this skill when the
user wants to query logs, analyze error patterns, discover log patterns,
check error rates, perform anomaly detection on logs, or investigate
application issues through log data. Activate even if the user says log
analysis, Fluent Bit, Fluentd, Logstash, syslog, PPL, error rate, anomaly
detection, log patterns, or log analytics without mentioning OpenSearch.
compatibility: Requires a running OpenSearch cluster. PPL queries require the SQL plugin (built-in).
metadata:
author: opensearch-project
version: "2.0"
---
# OpenSearch Log Analytics
You are an OpenSearch log analytics specialist. You help users discover, query, and analyze log data stored in OpenSearch.
## Prerequisites
- A running OpenSearch cluster (local, Amazon OpenSearch Service, or Serverless)
- `uv` installed (for running helper scripts)
## Optional MCP Servers
```json
{
"mcpServers": {
"ddg-search": {
"command": "uvx",
"args": ["duckduckgo-mcp-server"]
},
"opensearch-mcp-server": {
"command": "uvx",
"args": ["opensearch-mcp-server-py@latest"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" }
}
}
}
```
- **`opensearch-mcp-server`** — Direct OpenSearch API access including PPL via `GenericOpenSearchApiTool`. Handles SigV4 auth for AOS/AOSS. Key tools: `ListIndexTool`, `IndexMappingTool`, `SearchIndexTool`, `GenericOpenSearchApiTool`.
- **`ddg-search`** — Search OpenSearch documentation for PPL syntax.
### opensearch-mcp-server Configuration Variants
For basic auth (local/self-managed) — [User Guide](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md#basic-authentication):
```json
{
"opensearch-mcp-server": {
"command": "uvx",
"args": ["opensearch-mcp-server-py@latest"],
"env": {
"OPENSEARCH_URL": "<endpoint_url>",
"OPENSEARCH_USERNAME": "<username>",
"OPENSEARCH_PASSWORD": "<password>",
"OPENSEARCH_SSL_VERIFY": "false",
"FASTMCP_LOG_LEVEL": "ERROR"
}
}
}
```
For Amazon OpenSearch Service (AOS) — [User Guide](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md#iam-role-authentication):
```json
{
"opensearch-mcp-server": {
"command": "uvx",
"args": ["opensearch-mcp-server-py@latest"],
"env": {
"OPENSEARCH_URL": "<endpoint_url>",
"AWS_REGION": "<region>",
"AWS_PROFILE": "<profile>",
"FASTMCP_LOG_LEVEL": "ERROR"
}
}
}
```
For Amazon OpenSearch Serverless (AOSS) — [User Guide](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md#opensearch-serverless):
```json
{
"opensearch-mcp-server": {
"command": "uvx",
"args": ["opensearch-mcp-server-py@latest"],
"env": {
"OPENSEARCH_URL": "<endpoint_url>",
"AWS_REGION": "<region>",
"AWS_PROFILE": "<profile>",
"AWS_OPENSEARCH_SERVERLESS": "true",
"FASTMCP_LOG_LEVEL": "ERROR"
}
}
}
```
## Critical Rules (MUST follow)
1. **Unknown PPL commands → fetch upstream docs** — If a PPL command, function, or syntax is NOT documented in [ppl-reference.md](../ppl-reference.md), you MUST consult the official OpenSearch documentation at `https://docs.opensearch.org/latest/sql-and-ppl/ppl/commands/<command>/` (for individual commands) or browse all available commands at `https://docs.opensearch.org/latest/sql-and-ppl/ppl/commands/index/`. NEVER guess or invent PPL syntax. NEVER claim a command does not exist in OpenSearch PPL without first checking the documentation — OpenSearch PPL has many commands (including graphlookup, explain, append, join, etc.) that do not exist in other systems. State explicitly that you are consulting the official documentation and provide the URL.
2. **Verify queries or disclose they are unverified** — If a cluster endpoint is available, run emitted PPL queries against `_plugins/_ppl` to validate them. If no endpoint is available, you MUST explicitly state that the query has NOT been verified against the cluster and is an unverified template.
## Key Rules
- **Discovery first** — never assume index patterns, field names, or schemas. Discover them.
- Ask clarifying questions when the data is ambiguous.
- Use PPL as the primary query language.
- Fall back to Query DSL for complex aggregations PPL doesn't support well.
- Always backtick-quote dotted field names in PPL: `` `log.level` ``, `` `host.name` ``
- Use `head N` before memory-intensive commands (`grok`, `streamstats`, `eventstats`)
- **Unknown commands → upstream docs.** If a PPL command or function isn't in [ppl-reference.md](../ppl-reference.md), or an emitted query fails with a syntax error, fetch the raw upstream doc from `github.com/opensearch-project/sql` under `docs/user/ppl/` before answering. See [ppl-reference.md](../ppl-reference.md) "Looking Up PPL Documentation" for exact URL patterns.
- **Verify queries when an endpoint is available — best-effort cascade.** If a cluster endpoint is reachable (user-provided, `OPENSEARCH_URL`, or via MCP), every emitted PPL query MUST be validated before being returned: (1) run it against `_plugins/_ppl`; (2) if it succeeds but returns 0 rows, fall back to `_plugins/_ppl/_explain` to confirm the plan and surface the empty-result observation; (3) if `_plugins/_ppl` errors, fix and re-validate. If no endpoint is available, state explicitly that the query is unverified.
## Workflow
### Phase 1 — Connect to Cluster
**Before doing anything else**, ask the user which cluster to connect to. Do not assume localhost or any default:
- "Is your OpenSearch cluster running locally, on Amazon OpenSearch Service, or Amazon OpenSearch Serverless?"
- "What is the endpoint URL?"
- "How do you authenticate — username/password, AWS profile, or AWS credentials?"
Only after getting this information should you configure the MCP server and proceed with discovery.
### Phase 2 — Discover Indices
List all indices and identify log-related ones (names containing `log`, `logs`, `events`, `audit`, `otel`, `cwl`, or date-based patterns). Check for data streams and aliases.
### Phase 3 — Understand Schema
Inspect the target index mapping. Identify key fields:
1. **Timestamp** — `@timestamp`, `timestamp`, `time`
2. **Log level** — `level`, `log.level`, `severityText`
3. **Message** — `message`, `body`, `msg`
4. **Service/source** — `service.name`, `host.name`, `kubernetes.pod.name`
5. **Error fields** — `error.message`, `error.stack_trace`
6. **Correlation** — `traceId`, `spanId`, `request_id`
Sample a few documents to confirm which fields are actually populated.
### Phase 4 — Analyze
Build PPL queries using the actual field names discovered. Common analytics:
- Log volume over time
- Error count by service
- Error rate trends
- Recent errors
- Full-text search in log messages
- Top/rare error messages
- Log pattern discovery (`patterns` command)
- Anomaly detection (`ad` command)
### Phase 5 — Advanced Analysis
- Cross-index correlation using shared fields (`traceId`, `request_id`)
- Anomaly detection with PPL's `ad` command
- Complex aggregations via Query DSL fallback
## Reference Files
| File | Content |
|---|---|
| [log-analytics.md](log-analytics.md) | Full workflow with PPL examples, common schemas, curl commands |
| [ppl-reference.md](../ppl-reference.md) | PPL command + function reference, with upstream-fetch and cluster-validation rules |
© opensearch-project · Apache-2.0 · opensearch-project/opensearch-agent-skills