Debug Connector Example¶

File: examples/debug_connector.py

This example helps you understand connector APIs in detail and troubleshoot issues by showing verbose output and API responses.

Purpose¶

Perfect for:

Understanding API responses
Troubleshooting connector issues
Learning connector types and capabilities
Debugging configuration problems

What You’ll Learn¶

List and inspect available connector types
View detailed API responses
Understand connector structure
Debug common issues
Verify connector operations

Code Overview¶

The debug example walks through each step with detailed output:

1. List Existing Connectors¶

connectors_response = client.actions.get_all()
connectors = connectors_response.body
print(f"✓ Found {len(connectors)} existing connectors")
for conn in connectors:
    print(f"  - {conn.get('name', 'Unknown')} ({conn.get('id', 'No ID')})")

What This Shows:

All connectors currently in Kibana
Connector names and IDs
Helps identify existing connectors before creating new ones

2. List Available Connector Types¶

types_response = client.actions.list_types()
types = types_response.body
print(f"✓ Found {len(types)} connector types")
for conn_type in types:
    print(f"  - {conn_type.get('id', 'Unknown')}: {conn_type.get('name', 'Unknown')}")
    if conn_type.get("id") == ".index":
        print(f"    ✓ Index connector available: {conn_type.get('enabled', 'Unknown status')}")

What This Shows:

All available connector types in your Kibana instance
Whether each type is enabled
Specific details about the index connector

3. Create Connector with Verbose Output¶

response = client.actions.create(
    name="Debug Index Connector",
    connector_type_id=".index",
    config={
        "index": "miconnectedindex",
        "refresh": True,
        "executionTimeField": "@timestamp",
    },
)

print(f"✓ Response type: {type(response)}")
print(f"✓ Response meta: {response.meta}")
print(f"✓ Connector data: {response.body}")

What This Shows:

Response object structure
HTTP metadata (status code, headers, etc.)
Complete connector data including all fields

4. Verify Connector Creation¶

connector_data = response.body
if isinstance(connector_data, dict) and "id" in connector_data:
    connector_id = connector_data["id"]
    print(f"✓ Created connector with ID: {connector_id}")
    print(f"✓ Connector name: {connector_data.get('name', 'Unknown')}")
    print(f"✓ Connector type: {connector_data.get('connector_type_id', 'Unknown')}")

What This Shows:

How to safely extract data from responses
All fields returned by the API
Connector configuration details

Understanding Connector Types¶

Common Connector Types¶

The debug example helps you discover available types:

✓ Found 15 connector types
  - .email: Email
  - .index: Index
    ✓ Index connector available: True
  - .pagerduty: PagerDuty
  - .server-log: Server log
  - .servicenow: ServiceNow
  - .slack: Slack
  - .webhook: Webhook
  ...

Connector Type Details¶

Each connector type has:

id: Unique identifier (e.g., .index, .webhook)
name: Display name
enabled: Whether it’s available in your Kibana instance
enabled_in_config: Configuration-based availability
enabled_in_license: License-based availability

Response Structure¶

Create Response¶

{
    "id": "abc123-def456-ghi789",
    "name": "Debug Index Connector",
    "connector_type_id": ".index",
    "is_preconfigured": False,
    "is_deprecated": False,
    "is_missing_secrets": False,
    "config": {
        "index": "miconnectedindex",
        "refresh": True,
        "executionTimeField": "@timestamp"
    },
    "is_system_action": False
}

List Types Response¶

[
    {
        "id": ".index",
        "name": "Index",
        "enabled": True,
        "enabled_in_config": True,
        "enabled_in_license": True,
        "minimum_license_required": "basic",
        "supported_feature_ids": ["alerting", "uptime", "siem"]
    },
    ...
]

Debugging Techniques¶

1. Check Connector Availability¶

types = client.actions.list_types().body
index_type = next((t for t in types if t['id'] == '.index'), None)

if not index_type:
    print("❌ Index connector not available")
elif not index_type.get('enabled'):
    print("❌ Index connector is disabled")
    print(f"   Reason: {index_type.get('disabled_reason', 'Unknown')}")
else:
    print("✓ Index connector is available")

2. Inspect API Responses¶

response = client.actions.create(...)

# Check HTTP status
print(f"HTTP Status: {response.meta.status}")

# Check response headers
print(f"Headers: {response.meta.headers}")

# Check response body
print(f"Body: {json.dumps(response.body, indent=2)}")

3. Verify Configuration¶

connector = client.actions.get(id=connector_id).body

print("Connector Configuration:")
print(f"  Name: {connector['name']}")
print(f"  Type: {connector['connector_type_id']}")
print(f"  Config: {json.dumps(connector['config'], indent=2)}")
print(f"  Missing secrets: {connector.get('is_missing_secrets', False)}")

Common Debugging Scenarios¶

Scenario 1: Connector Type Not Found¶

Symptom: Error creating connector with specific type

Debug Steps:

List all available types
Check if the type exists
Verify the type is enabled
Check license requirements

types = client.actions.list_types().body
for t in types:
    if t['id'] == '.index':
        print(f"Enabled: {t['enabled']}")
        print(f"License: {t.get('minimum_license_required')}")
        print(f"Reason: {t.get('disabled_reason', 'N/A')}")

Scenario 2: Configuration Errors¶

Symptom: BadRequestError when creating connector

Debug Steps:

Check required configuration fields
Verify field types and values
Review error message details

try:
    connector = client.actions.create(
        name="Test",
        connector_type_id=".index",
        config={"index": "test"}  # Minimal config
    )
except BadRequestError as e:
    print(f"Configuration error: {e}")
    print(f"Response body: {e.body}")
    print(f"Status code: {e.status_code}")

Scenario 3: Permission Issues¶

Symptom: AuthorizationException or ForbiddenError

Debug Steps:

Check user permissions
Verify API key/credentials
Review required privileges

try:
    connectors = client.actions.get_all()
except AuthorizationException as e:
    print("❌ Insufficient permissions")
    print("   Required: actions:read, actions:create")
    print(f"   Error: {e}")

Running the Example¶

# With automatic configuration
python examples/debug_connector.py

# With verbose output
python examples/debug_connector.py 2>&1 | tee debug_output.log

Expected Output¶

📊 Kibana Configuration:
   URL: http://localhost:5601
   Auth: Basic authentication

Testing connection...
Listing existing connectors...
✓ Found 3 existing connectors
  - My Connector (conn-123)
  - Test Connector (conn-456)
  - Production Connector (conn-789)

Listing available connector types...
✓ Found 15 connector types
  - .email: Email
  - .index: Index
    ✓ Index connector available: True
  - .server-log: Server log
  - .slack: Slack
  - .webhook: Webhook
  ...

Creating index connector...
✓ Response type: <class 'elastic_transport.ObjectApiResponse'>
✓ Response meta: <ResponseMeta(status=200, http_version='1.1', ...)>
✓ Connector data: {'id': 'abc123', 'name': 'Debug Index Connector', ...}
✓ Created connector with ID: abc123
✓ Connector name: Debug Index Connector
✓ Connector type: .index

🎉 Debug connector created successfully!
   This example created a connector for debugging purposes.
Delete the debug connector? (y/N):

Troubleshooting Tips¶

Tip 1: Save Debug Output¶

python examples/debug_connector.py > debug_output.txt 2>&1

Review the output file to analyze API responses.

Tip 2: Use Python Debugger¶

import pdb

response = client.actions.create(...)
pdb.set_trace()  # Inspect response interactively

Tip 3: Enable HTTP Logging¶

import logging

# Enable HTTP request/response logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger('elastic_transport').setLevel(logging.DEBUG)

Tip 4: Check Kibana Logs¶

If connector creation fails, check Kibana server logs:

# Docker
docker logs kibana

# Systemd
journalctl -u kibana -f

Next Steps¶

After debugging:

Simple Example: Return to basic usage
- View Simple Example →
Comprehensive Example: Production patterns
- View Comprehensive Example →
Error Handling: Handle exceptions properly
- View Error Handling Guide →

Key Takeaways¶

✅ List types first: Understand what’s available

✅ Inspect responses: Learn the API structure

✅ Verify operations: Confirm each step succeeded

✅ Check permissions: Ensure adequate access

✅ Review configuration: Validate all settings

Debug Connector Example¶

Purpose¶

What You’ll Learn¶

Code Overview¶

1. List Existing Connectors¶

2. List Available Connector Types¶

3. Create Connector with Verbose Output¶

4. Verify Connector Creation¶

Understanding Connector Types¶

Common Connector Types¶

Connector Type Details¶

Response Structure¶

Create Response¶

List Types Response¶

Debugging Techniques¶

1. Check Connector Availability¶

2. Inspect API Responses¶

3. Verify Configuration¶

Common Debugging Scenarios¶

Scenario 1: Connector Type Not Found¶

Scenario 2: Configuration Errors¶

Scenario 3: Permission Issues¶

Running the Example¶

Expected Output¶

Troubleshooting Tips¶

Tip 1: Save Debug Output¶

Tip 2: Use Python Debugger¶

Tip 3: Enable HTTP Logging¶

Tip 4: Check Kibana Logs¶

Next Steps¶

Key Takeaways¶

Related Examples¶

Related Documentation¶