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

Getting Started¶

New to kibana-py? Start here:

Basic Usage - Client initialization, authentication, and fundamental patterns
Connectors - Create and manage Kibana connectors (actions)
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 (Actions)¶

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.actions.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.actions.create(...)
except ConflictError:
    print("Already exists")
except NotFoundError:
    print("Not found")

Pattern 4: Space-Scoped Operations¶

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

# Method 2: Space-scoped client
marketing_client = client.space("marketing")
connector = marketing_client.actions.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