Basic Usage Examples¶

This section demonstrates the fundamental patterns for using the Kibana Python client. These examples cover client initialization, authentication, response handling, and basic configuration.

Overview¶

The basic usage examples show you how to:

Initialize the Kibana client with different authentication methods
Use context managers for automatic resource cleanup
Handle API responses correctly
Configure per-request options
Set up connection pooling and retry logic

Example Files¶

basic_usage.py¶

Location: examples/basic_usage.py

Purpose: Comprehensive demonstration of fundamental client patterns

What You’ll Learn:

Multiple ways to initialize the Kibana client
Different authentication methods (API key, basic auth, bearer token)
Using context managers for automatic cleanup
Accessing response data correctly
Per-request configuration with the options() method
Advanced connection configuration

When to Use: Start here if you’re new to kibana-py or need to understand the core client patterns.

Key Concepts¶

Client Initialization¶

The Kibana client can be initialized in several ways:

from kibana import Kibana

# Simple initialization with URL only
client = Kibana("http://localhost:5601")

# With basic authentication
client = Kibana("http://localhost:5601", basic_auth=("elastic", "password"))

# With API key
client = Kibana("http://localhost:5601", api_key="your_api_key")

# With bearer token
client = Kibana("http://localhost:5601", bearer_auth="your_bearer_token")

Context Manager Pattern¶

The recommended way to use the client is with a context manager, which automatically closes the connection:

from kibana import Kibana

with Kibana("http://localhost:5601", basic_auth=("elastic", "password")) as client:
    # Use the client
    types = client.actions.list_types()
    print(f"Found {len(types.body)} connector types")
# Client is automatically closed here

Why Use Context Managers?

Automatic resource cleanup
Prevents connection leaks
Cleaner, more Pythonic code
Handles exceptions gracefully

Response Handling¶

All API methods return an ObjectApiResponse object. Always access the .body attribute to get the actual data:

# Correct: Access .body attribute
response = client.actions.list_types()
types = response.body  # This is the actual data
print(f"Found {len(types)} types")

# Also correct: Access metadata
print(f"HTTP Status: {response.meta.status}")
print(f"HTTP Version: {response.meta.http_version}")

# Incorrect: Don't treat response as a dictionary
# types = response["types"]  # This will fail!

Per-Request Configuration¶

Use the options() method to configure individual requests without affecting the client:

# Set a longer timeout for a specific request
response = client.options(request_timeout=60).actions.list_types()

# Add custom headers
response = client.options(
    headers={"X-Custom-Header": "value"}
).actions.list_types()

# Chain multiple options
response = client.options(
    request_timeout=30,
    headers={"X-Request-ID": "12345"}
).actions.list_types()

Advanced Configuration¶

For production use, configure connection pooling, retries, and timeouts:

from kibana import Kibana

client = Kibana(
    hosts=["http://localhost:5601"],
    basic_auth=("elastic", "password"),
    # Timeout settings
    request_timeout=30.0,
    # Retry configuration
    max_retries=3,
    retry_on_timeout=True,
    retry_on_status=[502, 503, 504],
    # Connection pooling
    connections_per_node=10,
)

Automatic Configuration¶

All examples support automatic configuration from multiple sources:

Environment variables:

export KIBANA_URL="http://localhost:5601"
export KIBANA_API_KEY="your_api_key"
# or
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="your_password"

Local development setup: If using elastic-start-local/, credentials are automatically read from elastic-start-local/.env
Defaults: Falls back to http://localhost:5601 with no authentication

Running the Example¶

# With automatic configuration
python examples/basic_usage.py

# With environment variables
export KIBANA_URL="http://localhost:5601"
export KIBANA_USERNAME="elastic"
export KIBANA_PASSWORD="changeme"
python examples/basic_usage.py

What the Example Demonstrates¶

Basic Initialization: Different ways to create a Kibana client
Context Manager: Automatic resource cleanup
Response Handling: Correct way to access API response data
Per-Request Options: Customizing individual requests
Connection Configuration: Advanced settings for production use
Multiple Hosts: High availability configuration

Next Steps¶

After understanding basic usage, explore:

Authentication Guide - Detailed authentication patterns
Connector Examples - Working with Kibana connectors
Error Handling - Exception handling patterns

Common Patterns¶

Pattern 1: Quick Script¶

For quick scripts or testing:

from kibana import Kibana

client = Kibana("http://localhost:5601")
try:
    # Do something
    response = client.status.get_status()
    print(response.body["status"]["overall"]["level"])
finally:
    client.close()

Pattern 2: Production Application¶

For production applications:

from kibana import Kibana

with Kibana(
    "http://localhost:5601",
    api_key="your_api_key",
    request_timeout=30.0,
    max_retries=3
) as client:
    # Application logic
    pass

Pattern 3: Configuration from Environment¶

For flexible deployment:

import os
from kibana import Kibana

kibana_url = os.getenv("KIBANA_URL", "http://localhost:5601")
api_key = os.getenv("KIBANA_API_KEY")

with Kibana(kibana_url, api_key=api_key) as client:
    # Application logic
    pass

Best Practices¶

Always use context managers for automatic cleanup
Access .body attribute for response data
Configure timeouts appropriate for your use case
Use environment variables for credentials
Enable retries for production applications
Handle exceptions appropriately (see error handling guide)

Troubleshooting¶

Connection Refused¶

Problem: ConnectionError: Connection refused

Solution: Ensure Kibana is running and accessible at the specified URL

Authentication Failed¶

Problem: AuthenticationException: Authentication failed

Solution: Verify your credentials are correct and have the necessary permissions

Timeout Errors¶

Problem: ConnectionTimeout: Request timed out

Solution: Increase the timeout or check network connectivity:

client = Kibana("http://localhost:5601", request_timeout=60.0)