Examples¶

This section provides comprehensive examples demonstrating how to use the Kibana Python client. Examples progress from simple to advanced, covering all major features.

Examples

Per-Namespace Management Scripts¶

Every API namespace ships with a runnable, end-to-end management script in the repository’s examples/ directory. Each script demonstrates the full lifecycle for its namespace (create, read, update, delete, plus namespace-specific operations) against a live Kibana instance, with automatic configuration and cleanup:

Script	Namespace
`dashboards_management.py`	`client.dashboards` — the new Dashboards HTTP API (tech preview)
`visualizations_management.py`	`client.visualizations` — Lens visualizations (tech preview)
`alerting_management.py`	`client.alerting` — rules, snooze, backfills
`data_views_management.py`	`client.data_views` — data views and runtime fields
`cases_management.py`	`client.cases` — cases, comments, files
`connectors_management.py`	`client.connectors` — connector CRUD and execution
`spaces_management.py`	`client.spaces` — space CRUD
`saved_objects_management.py`	`client.saved_objects` — export/import and legacy CRUD
`status_management.py`	`client.status` — status and stats
`security_management.py`	`client.security` — roles and sessions
`short_urls_management.py`	`client.short_urls` — short URL create/resolve
`slos_management.py`	`client.slos` — SLO lifecycle
`synthetics_management.py`	`client.synthetics` — monitors, params, private locations
`uptime_management.py`	`client.uptime` — Uptime settings
`streams_management.py`	`client.streams` — wired streams, queries, attachments
`workflows_management.py`	`client.workflows` — workflows and executions
`agent_builder_management.py`	`client.agent_builder` — agents, tools, conversations
`apm_management.py`	`client.apm` — agent configs, annotations, source maps
`maintenance_windows_management.py`	`client.maintenance_windows` — window lifecycle
`ml_management.py`	`client.ml` — ML saved object sync and spaces
`logstash_management.py`	`client.logstash` — centralized pipeline management
`task_manager_management.py`	`client.task_manager` — health monitoring
`upgrade_assistant_management.py`	`client.upgrade_assistant` — upgrade readiness
`observability_ai_assistant_management.py`	`client.observability_ai_assistant` — LLM chat completion
`actions_management.py`	`client.actions` — deprecated alias of `client.connectors`

Run any of them directly once your stack is up:

python examples/dashboards_management.py

Getting Started¶

New to kibana-py? Start here:

Basic Usage - Client initialization, authentication, and fundamental patterns
Connectors - Create and manage Kibana connectors
Spaces - Organize resources with Kibana Spaces
Saved Objects - Manage dashboards, visualizations, and more

Example Categories¶

Basic Usage¶

Learn the fundamentals of using the Kibana client:

Basic Usage - Client initialization, authentication, response handling, and configuration

Start here if you’re new to kibana-py.

Connectors¶

Create and manage connectors for alerting and automation:

Connector Overview - Introduction to connectors
Simple Example - Minimal connector creation (~50 lines)
Debug Example - Troubleshooting and API inspection
Comprehensive Example - Production-ready patterns

Perfect for integrating with external systems.

Spaces¶

Organize Kibana resources with spaces for multi-tenancy:

Space Overview - Introduction to Kibana Spaces
Simple Example - Basic space creation
Management Example - Full CRUD operations

Essential for multi-tenant applications.

Saved Objects¶

Manage Kibana saved objects programmatically:

Saved Objects Overview - Introduction to saved objects
Management Example - CRUD operations and version control

For managing dashboards and visualizations.

Async Operations¶

Use the async client for concurrent operations:

Async Overview - Introduction to AsyncKibana
Async Patterns - Concurrent operations and best practices

For high-performance applications.

Observability¶

Monitor your application with OpenTelemetry:

Observability - Tracing and log forwarding

For production monitoring and debugging.

Example Progression¶

Level 1: Simple Examples¶

Minimal code to get started quickly:

Simple Connector - ~50 lines
Simple Space - ~40 lines
Basic Usage - Fundamental patterns

Best for: Learning, prototyping, quick scripts

Level 2: Debug Examples¶

Understand API responses and troubleshoot issues:

Debug Connector - Verbose output and API inspection

Best for: Troubleshooting, understanding the API

Level 3: Comprehensive Examples¶

Production-ready patterns with error handling:

Comprehensive Connector - Class-based, full lifecycle
Space Management - Complete CRUD operations
Saved Objects Management - Version control and bulk operations

Best for: Production applications, robust implementations

Running Examples¶

Prerequisites¶

Running Kibana instance (default: http://localhost:5601)
Elasticsearch cluster with write permissions
Authentication (optional but recommended):
- API key, or
- Basic authentication (username/password), or
- Bearer token

Quick Start with elastic-start-local¶

The easiest way to run examples:

# Start local Elastic Stack
./local-stack.sh -o start

# Run any example
python examples/simple_index_connector.py

Manual Configuration¶

Set environment variables:

export KIBANA_URL="http://localhost:5601"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="changeme"

python examples/simple_index_connector.py

Automatic Configuration¶

All examples support automatic configuration from multiple sources:

Environment variables: KIBANA_URL, KIBANA_API_KEY, etc.
Local development setup: Reads from elastic-start-local/.env
Defaults: Falls back to http://localhost:5601

Common Patterns¶

Pattern 1: Context Manager¶

from kibana import Kibana

with Kibana("http://localhost:5601") as client:
    # Use client
    response = client.status.get_status()
# Automatic cleanup

Pattern 2: Response Handling¶

# Always access .body attribute
response = client.connectors.list_types()
types = response.body  # This is the actual data

# Access metadata
print(f"Status: {response.meta.status}")

Pattern 3: Error Handling¶

from kibana.exceptions import ConflictError, NotFoundError

try:
    connector = client.connectors.create(...)
except ConflictError:
    print("Already exists")
except NotFoundError:
    print("Not found")

Pattern 4: Space-Scoped Operations¶

# Method 1: space_id parameter
connector = client.connectors.create(
    name="Test",
    connector_type_id=".index",
    config={},
    space_id="marketing"
)

# Method 2: Space-scoped client
marketing_client = client.space("marketing")
connector = marketing_client.connectors.create(
    name="Test",
    connector_type_id=".index",
    config={}
)

Example Features¶

All examples include:

✅ Automatic configuration from environment or local setup
✅ Interactive cleanup to prevent resource accumulation
✅ Proper error handling with specific exceptions
✅ Response handling using .body attribute
✅ OpenTelemetry support for tracing and logging
✅ Clear output with status messages

Best Practices¶

Start simple - Begin with simple examples, progress to comprehensive
Use context managers - Automatic resource cleanup
Handle errors - Catch specific exceptions
Clean up resources - Delete test connectors and spaces
Enable observability - Use tracing for production applications

Troubleshooting¶

Connection Issues¶

Problem: ConnectionError: Connection refused

Solution: Ensure Kibana is running at the specified URL

Authentication Issues¶

Problem: AuthenticationException: Authentication failed

Solution: Verify credentials are correct

Permission Issues¶

Problem: AuthorizationException: Insufficient permissions

Solution: Ensure user has required permissions for the operation

Next Steps¶

Start with Basic Usage to understand fundamentals
Explore Connectors for integration patterns
Learn Spaces for multi-tenancy
Review User Guide for detailed documentation
Check API Reference for complete API documentation