obz-elasticsearch: Elasticsearch Provider
Quick Reference
| Field | Value |
|---|
| Aliases | es, elasticsearch |
| Signals | Log, Trace |
| Query language | Elasticsearch Query DSL (Lucene-based) |
| Auth | Basic auth, bearer token, or API key (in config.yaml) |
| Provider flags | --index (required at runtime) |
| Supported cmds | log search, trace search, trace get |
Supported Commands
obz log search # Search log entries in an Elasticsearch index
obz trace search # Search trace spans in an Elasticsearch index
obz trace get # Retrieve a trace by ID from Elasticsearch
Provider-Specific Flags
| Flag | Type | Required | Description |
|---|
--index | String | Yes | Index name or pattern to query |
The --index flag is declared optional at the clap level (so other
providers don't error), but Elasticsearch enforces it at runtime.
Authentication
Configure auth in config.yaml under providers.<name>.auth.
Priority: API key > bearer token > basic auth.
Basic auth:
# config.yaml
providers:
es:
endpoint: https://es.example.com
index: logs-*
auth:
username: elastic
password: ${env:ES_PASS}
Bearer token:
auth:
token: ${env:ES_TOKEN}
API key (Authorization: ApiKey <key>):
auth:
api-key: ${env:ES_API_KEY}
Then query with just -p:
obz log search -p es -q 'level:ERROR' --from now-1h
Query Language
Elasticsearch accepts Lucene-based query strings in the -q parameter.
The syntax is nearly identical to OpenSearch.
Common Patterns
level:ERROR # field match
level:ERROR AND service:api # boolean AND
status:(404 OR 500) # grouped OR
message:"connection refused" # phrase match
host:web-* AND NOT path:/health # wildcards and negation
response_time:[500 TO *] # range query
Tips
- Field names are case-sensitive and depend on your index mapping.
- Use double quotes for exact phrase matches.
- Leading wildcards (
*error) are disabled by default for performance.
Elasticsearch vs OpenSearch
Both providers share the same query syntax and flag surface. The main
difference is the backend API version and endpoint format.
| Aspect | Elasticsearch | OpenSearch |
|---|
| Alias | es | os |
| Auth options | Basic + bearer + API key | Basic + bearer |
| API lineage | Elastic N.V. | AWS fork |
If your cluster is OpenSearch, use the os provider instead.
Examples
Search logs by level:
obz log search -p es --index 'logs-*' -q 'level:ERROR' --from now-1h
Search with boolean operators:
obz log search -p es --index 'app-logs' \
-q 'service:api AND status:500' --from now-6h
Search traces:
obz trace search -p es --index 'traces-*' -q 'service:frontend' --from now-1h
Retrieve a specific trace:
obz trace get -p es --index 'traces-*' abc123def456