Connector Examples¶
Connectors (also called Actions) in Kibana allow you to integrate with external systems for alerting, automation, and data forwarding. This section demonstrates how to create, configure, and use connectors programmatically.
Connector Examples
Overview¶
The connector examples progress from simple to comprehensive, showing you:
Basic connector creation and execution
Debugging and troubleshooting techniques
Production-ready patterns with error handling
Space-scoped connector operations
Example Progression¶
We provide three levels of connector examples, each building on the previous:
1. Simple Example (simple_index_connector.py)¶
Purpose: Minimal code to get started quickly
What You’ll Learn:
Create an index connector in ~50 lines of code
Write a document to Elasticsearch via the connector
Clean up resources interactively
When to Use: Perfect starting point for learning connectors or quick prototyping
2. Debug Example (debug_connector.py)¶
Purpose: Understand API responses and troubleshoot issues
What You’ll Learn:
List available connector types
Inspect API responses in detail
Debug connector creation issues
Understand connector configuration
When to Use: When you need to troubleshoot connector issues or understand the API better
3. Advanced Example (connector_management.py)¶
Purpose: Production-ready patterns and advanced features
What You’ll Learn:
Class-based connector management
Comprehensive error handling
Update and delete operations
Batch document writing
Logging and observability integration
When to Use: Building production applications that manage connectors
What Are Connectors?¶
Connectors are Kibana’s way of integrating with external systems. They can:
Write data to Elasticsearch indices (index connector)
Send notifications via email, Slack, webhooks
Trigger actions in external systems
Forward logs to monitoring systems
Index Connector Basics¶
The index connector is one of the most commonly used connector types. It writes documents to Elasticsearch indices.
Configuration¶
config = {
"index": "my-index-name", # Target index
"refresh": True, # Refresh after write
"executionTimeField": "@timestamp" # Timestamp field
}
Document Structure¶
Documents can contain any valid JSON data:
document = {
"@timestamp": "2024-01-01T12:00:00Z",
"message": "Application started",
"level": "INFO",
"service": "web-server",
"host": "server-01",
# ... any other fields
}
Common Use Cases¶
1. Application Logging¶
Write application logs to Elasticsearch for centralized logging:
connector = client.actions.create(
name="App Logs Connector",
connector_type_id=".index",
config={"index": "app-logs", "refresh": True}
)
# Write log entry
client.actions.execute(
id=connector.body["id"],
params={"documents": [{
"@timestamp": datetime.now(UTC).isoformat(),
"level": "ERROR",
"message": "Database connection failed",
"service": "api-server"
}]}
)
2. Metrics Collection¶
Forward metrics to Elasticsearch:
connector = client.actions.create(
name="Metrics Connector",
connector_type_id=".index",
config={"index": "app-metrics", "refresh": False}
)
# Write metrics
client.actions.execute(
id=connector.body["id"],
params={"documents": [{
"@timestamp": datetime.now(UTC).isoformat(),
"metric_name": "response_time",
"value": 150.5,
"unit": "ms",
"endpoint": "/api/users"
}]}
)
3. Event Tracking¶
Track application events:
connector = client.actions.create(
name="Events Connector",
connector_type_id=".index",
config={"index": "app-events", "refresh": True}
)
# Track event
client.actions.execute(
id=connector.body["id"],
params={"documents": [{
"@timestamp": datetime.now(UTC).isoformat(),
"event_type": "user_signup",
"user_id": "user123",
"source": "web",
"metadata": {"plan": "premium"}
}]}
)
Space-Scoped Connectors¶
Connectors can be created in specific Kibana spaces for multi-tenancy:
# Create connector in a specific space
connector = client.actions.create(
name="Marketing Team Connector",
connector_type_id=".index",
config={"index": "marketing-data"},
space_id="marketing-team"
)
# Or use a space-scoped client
marketing_client = client.space("marketing-team")
connector = marketing_client.actions.create(
name="Marketing Team Connector",
connector_type_id=".index",
config={"index": "marketing-data"}
)
See Space-Scoped Connector Example for more details.
Error Handling¶
All connector operations can raise exceptions:
from kibana.exceptions import ConflictError, BadRequestError, NotFoundError
try:
connector = client.actions.create(
name="My Connector",
connector_type_id=".index",
config={"index": "my-index"}
)
except ConflictError:
print("Connector with this name already exists")
except BadRequestError as e:
print(f"Invalid configuration: {e}")
except NotFoundError:
print("Connector type not found")
Cleanup Best Practices¶
All examples include interactive cleanup to prevent connector accumulation:
# At the end of your script
cleanup = input("Delete the connector? (y/N): ").lower().strip()
if cleanup == 'y':
try:
client.actions.delete(id=connector_id)
print("✓ Connector deleted")
except Exception as e:
# Verify deletion
try:
client.actions.get(id=connector_id)
print(f"❌ Failed to delete: {e}")
except NotFoundError:
print("✓ Connector deleted (confirmed)")
Available Connector Types¶
Beyond index connectors, Kibana supports many connector types:
.index- Write to Elasticsearch indices.server-log- Write to Kibana server logs.webhook- HTTP webhooks.slack- Slack notifications.email- Email notifications.pagerduty- PagerDuty integration.servicenow- ServiceNow integrationAnd many more…
List available types:
types = client.actions.list_types()
for connector_type in types.body:
print(f"{connector_type['id']}: {connector_type['name']}")
Next Steps¶
Start with the Simple Example to understand the basics
Use the Debug Example when troubleshooting
Study the Comprehensive Example for production patterns
Explore Space-Scoped Operations for multi-tenancy
Review Error Handling for robust applications