tessl/pypi-datadog

The Datadog Python library provides tools for interacting with Datadog's monitoring platform through HTTP API client functionality, DogStatsD metrics client, and command-line tools.

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/pypi-datadog
Author: tessl

Core initialization and configuration system for setting up API authentication, StatsD connection parameters, and global library behavior. Provides centralized configuration management for all Datadog Python library components.

Capabilities

Library Initialization

Configure all Datadog library components with a single initialization call, setting up API credentials, connection parameters, and behavioral options.

def initialize(
    api_key=None,
    app_key=None,
    host_name=None,
    api_host=None,
    statsd_host=None,
    statsd_port=None,
    statsd_disable_aggregation=True,
    statsd_disable_buffering=True,
    statsd_aggregation_flush_interval=0.3,
    statsd_use_default_route=False,
    statsd_socket_path=None,
    statsd_namespace=None,
    statsd_max_samples_per_context=0,
    statsd_constant_tags=None,
    return_raw_response=False,
    hostname_from_config=True,
    cardinality=None,
    **kwargs
):
    """
    Initialize and configure Datadog API and StatsD modules.
    
    Parameters:
    - api_key (str): Datadog API key for authentication
    - app_key (str): Datadog application key for API access
    - host_name (str): Override hostname for metrics and events
    - api_host (str): Datadog API endpoint URL (default: https://api.datadoghq.com)
    - statsd_host (str): DogStatsD server hostname (default: localhost)
    - statsd_port (int): DogStatsD server port (default: 8125)
    - statsd_disable_aggregation (bool): Disable client-side aggregation
    - statsd_disable_buffering (bool): Disable metric buffering
    - statsd_aggregation_flush_interval (float): Aggregation flush interval in seconds
    - statsd_use_default_route (bool): Auto-detect StatsD host from default route
    - statsd_socket_path (str): Unix Domain Socket path (overrides host/port)
    - statsd_namespace (str): Prefix for all metric names
    - statsd_max_samples_per_context (int): Max samples per metric context
    - statsd_constant_tags (list): Tags applied to all metrics
    - return_raw_response (bool): Return raw HTTP response objects
    - hostname_from_config (bool): Get hostname from Datadog agent config
    - cardinality (str): Global cardinality level ('none', 'low', 'orchestrator', 'high')
    - **kwargs: Additional HTTP client configuration options
    """

Environment Variable Configuration

Automatic configuration from environment variables with precedence over explicit parameters.

# Environment variables (in order of precedence):
# API Authentication:
#   DATADOG_API_KEY or DD_API_KEY
#   DATADOG_APP_KEY or DD_APP_KEY

# API Host:  
#   DATADOG_HOST (default: https://api.datadoghq.com)

# Cardinality:
#   DATADOG_CARDINALITY or DD_CARDINALITY

# StatsD Configuration:
#   DD_STATSD_HOST
#   DD_STATSD_PORT  
#   DD_STATSD_SOCKET_PATH

HTTP Client Configuration

Advanced HTTP client settings for connection management, timeouts, retries, and proxy configuration.

# HTTP Configuration Options (passed via **kwargs to initialize()):

# Connection Settings:
# - proxies (dict): Proxy configuration {'http': 'http://proxy:8080', 'https': 'https://proxy:8080'}
# - timeout (int): Request timeout in seconds (default: 60)
# - max_timeouts (int): Maximum timeout retries (default: 3)
# - max_retries (int): Maximum request retries (default: 3)
# - backoff_period (int): Backoff period between retries in seconds (default: 300)

# SSL/TLS Settings:
# - cacert (str|bool): Path to CA certificate file, True for system certs, False to skip verification

# Response Handling:
# - mute (bool): Suppress API errors and client errors (default: True)
# - return_raw_response (bool): Include raw response object in API returns

StatsD Client Configuration

Detailed configuration options for the DogStatsD client behavior, transport, and performance optimization.

# StatsD Configuration Parameters:

# Connection:
# - statsd_host (str): DogStatsD server hostname
# - statsd_port (int): DogStatsD server port  
# - statsd_socket_path (str): Unix Domain Socket path (preferred over UDP)
# - statsd_use_default_route (bool): Dynamically resolve host from default route

# Performance:
# - statsd_disable_buffering (bool): Disable UDP packet buffering
# - statsd_disable_aggregation (bool): Disable client-side metric aggregation
# - statsd_aggregation_flush_interval (float): Aggregation flush interval
# - statsd_max_samples_per_context (int): Maximum samples per metric context

# Metadata:
# - statsd_namespace (str): Prefix added to all metric names
# - statsd_constant_tags (list): Tags applied to all metrics
# - cardinality (str): Cardinality level for all metrics

Global Configuration State

Access and modify global configuration state for runtime adjustments and debugging.

# Global configuration variables (datadog.api module):

# API Settings:
# api._api_key - Current API key
# api._application_key - Current application key  
# api._api_host - Current API endpoint
# api._host_name - Current hostname
# api._api_version - API version (default: "v1")

# HTTP Settings:
# api._proxies - Proxy configuration
# api._timeout - Request timeout
# api._max_retries - Maximum retries
# api._mute - Error suppression setting
# api._return_raw_response - Raw response setting

# StatsD Global Instance:
# statsd - Global DogStatsd instance configured by initialize()

Usage Examples

Basic Configuration

from datadog import initialize

# Simple configuration with API keys
initialize(
    api_key="your-datadog-api-key",
    app_key="your-datadog-app-key"
)

# Configuration with custom API host (for EU instance)
initialize(
    api_key="your-api-key",
    app_key="your-app-key", 
    api_host="https://api.datadoghq.eu"
)

Environment Variable Configuration

import os
from datadog import initialize

# Set environment variables
os.environ['DATADOG_API_KEY'] = 'your-api-key'
os.environ['DATADOG_APP_KEY'] = 'your-app-key'
os.environ['DATADOG_HOST'] = 'https://api.datadoghq.eu'

# Initialize without parameters - uses environment variables
initialize()

# Override environment variables with explicit parameters
initialize(
    api_key="different-api-key",  # Overrides DATADOG_API_KEY
    statsd_host="custom-statsd-host"
)

StatsD Configuration

from datadog import initialize

# Configure StatsD with custom settings
initialize(
    api_key="your-api-key",
    app_key="your-app-key",
    statsd_host="statsd.internal.com",
    statsd_port=8125,
    statsd_namespace="myapp",
    statsd_constant_tags=["env:production", "service:web"],
    statsd_disable_aggregation=False,  # Enable aggregation
    statsd_aggregation_flush_interval=1.0,  # Flush every second
    statsd_max_samples_per_context=100
)

Unix Domain Socket Configuration

from datadog import initialize

# Use Unix Domain Socket for better performance
initialize(
    api_key="your-api-key",
    app_key="your-app-key",
    statsd_socket_path="/var/run/datadog/dsd.socket",
    statsd_constant_tags=["transport:uds"]
)

Container and Kubernetes Configuration

from datadog import initialize

# Configuration for containerized environments
initialize(
    api_key="your-api-key",
    app_key="your-app-key",
    statsd_use_default_route=True,  # Auto-detect StatsD host
    statsd_constant_tags=[
        "container_name:web-server",
        "k8s_namespace:production",
        "k8s_pod_name:web-server-abc123"
    ],
    hostname_from_config=False,  # Don't use agent config in containers
    host_name="web-server-pod-1"  # Explicit hostname
)

HTTP Client Advanced Configuration

from datadog import initialize

# Advanced HTTP client configuration
initialize(
    api_key="your-api-key",
    app_key="your-app-key",
    
    # Proxy configuration
    proxies={
        'http': 'http://proxy.company.com:8080',
        'https': 'https://proxy.company.com:8080'
    },
    
    # Timeout and retry settings
    timeout=30,
    max_retries=5,
    max_timeouts=2,
    backoff_period=60,
    
    # SSL configuration
    cacert="/path/to/ca-certificates.pem",
    
    # Response handling
    mute=False,  # Don't suppress errors
    return_raw_response=True  # Include raw HTTP response
)

High Cardinality Configuration

from datadog import initialize

# Configure for high cardinality metrics
initialize(
    api_key="your-api-key",
    app_key="your-app-key",
    cardinality="high",  # Enable high cardinality
    statsd_constant_tags=[
        "service:microservice-a",
        "version:1.2.3",
        "datacenter:us-east-1"
    ]
)

Development vs Production Configuration

from datadog import initialize
import os

def configure_datadog():
    """Configure Datadog based on environment."""
    
    environment = os.environ.get('ENVIRONMENT', 'development')
    
    if environment == 'production':
        # Production configuration
        initialize(
            api_key=os.environ['DATADOG_API_KEY'],
            app_key=os.environ['DATADOG_APP_KEY'],
            api_host="https://api.datadoghq.com",
            statsd_host="datadog-agent.monitoring.svc.cluster.local",
            statsd_constant_tags=["env:production"],
            cardinality="orchestrator",
            statsd_disable_aggregation=False,
            mute=True  # Suppress errors in production
        )
    else:
        # Development configuration  
        initialize(
            api_key=os.environ.get('DATADOG_API_KEY', 'dummy-key'),
            app_key=os.environ.get('DATADOG_APP_KEY', 'dummy-key'),
            statsd_host="localhost",
            statsd_constant_tags=["env:development"],
            mute=False,  # Show errors in development
            return_raw_response=True  # Debug HTTP responses
        )

configure_datadog()

Runtime Configuration Updates

from datadog import initialize, api, statsd

# Initial configuration
initialize(api_key="initial-key", app_key="initial-app-key")

# Update API configuration at runtime
api._api_key = "new-api-key"
api._application_key = "new-app-key"
api._timeout = 30

# Update StatsD configuration at runtime
statsd.host = "new-statsd-host"
statsd.port = 8126
statsd.namespace = "updated_namespace"
statsd.constant_tags = ["updated:true"]

# Close and reconnect with new settings
statsd.close_socket()

Configuration Validation

from datadog import initialize, api
import sys

def validate_configuration():
    """Validate Datadog configuration before use."""
    
    if not api._api_key:
        print("ERROR: Datadog API key not configured")
        sys.exit(1)
        
    if not api._application_key:
        print("ERROR: Datadog application key not configured")
        sys.exit(1)
        
    print(f"Datadog configured:")
    print(f"  API Host: {api._api_host}")
    print(f"  Hostname: {api._host_name}")
    print(f"  StatsD: {statsd.host}:{statsd.port}")
    print(f"  Namespace: {statsd.namespace}")
    print(f"  Constant Tags: {statsd.constant_tags}")

# Configure and validate
initialize(
    api_key="your-api-key",
    app_key="your-app-key",
    statsd_namespace="myapp",
    statsd_constant_tags=["service:web"]
)

validate_configuration()

Multi-Environment Configuration Class

from datadog import initialize
import os
from typing import Optional, List, Dict

class DatadogConfig:
    """Centralized Datadog configuration management."""
    
    def __init__(
        self,
        environment: str,
        api_key: Optional[str] = None,
        app_key: Optional[str] = None,
        service_name: str = "unknown-service",
        version: str = "1.0.0"
    ):
        self.environment = environment
        self.api_key = api_key or os.environ.get('DATADOG_API_KEY')
        self.app_key = app_key or os.environ.get('DATADOG_APP_KEY')
        self.service_name = service_name
        self.version = version
        
    def get_statsd_config(self) -> Dict:
        """Get StatsD configuration for environment."""
        
        base_tags = [
            f"env:{self.environment}",
            f"service:{self.service_name}",
            f"version:{self.version}"
        ]
        
        if self.environment == 'production':
            return {
                'statsd_host': 'datadog-agent.monitoring',
                'statsd_port': 8125,
                'statsd_constant_tags': base_tags + ['tier:production'],
                'statsd_disable_aggregation': False,
                'cardinality': 'orchestrator'
            }
        elif self.environment == 'staging':
            return {
                'statsd_host': 'datadog-agent.staging',
                'statsd_port': 8125,
                'statsd_constant_tags': base_tags + ['tier:staging'],
                'cardinality': 'low'
            }
        else:  # development/local
            return {
                'statsd_host': 'localhost',
                'statsd_port': 8125,
                'statsd_constant_tags': base_tags + ['tier:development'],
                'cardinality': 'none'
            }
    
    def initialize_datadog(self):
        """Initialize Datadog with environment-specific configuration."""
        
        statsd_config = self.get_statsd_config()
        
        initialize(
            api_key=self.api_key,
            app_key=self.app_key,
            **statsd_config
        )

# Usage
config = DatadogConfig(
    environment=os.environ.get('ENVIRONMENT', 'development'),
    service_name='user-service',
    version='2.1.0'
)

config.initialize_datadog()

Configuration Best Practices

Security

# Good: Use environment variables for sensitive data
import os
from datadog import initialize

initialize(
    api_key=os.environ['DATADOG_API_KEY'],
    app_key=os.environ['DATADOG_APP_KEY']
)

# Avoid: Hardcoding credentials in source code
initialize(
    api_key="abc123...",  # Don't do this
    app_key="def456..."   # Don't do this
)

Performance Optimization

# For high-throughput applications
initialize(
    api_key=os.environ['DATADOG_API_KEY'],
    app_key=os.environ['DATADOG_APP_KEY'],
    
    # Enable aggregation to reduce network traffic
    statsd_disable_aggregation=False,
    statsd_aggregation_flush_interval=1.0,
    
    # Use Unix Domain Socket for better performance
    statsd_socket_path="/var/run/datadog/dsd.socket",
    
    # Batch metrics for efficiency
    statsd_max_samples_per_context=1000
)

Consistent Tagging Strategy

# Establish consistent tagging across all metrics
initialize(
    api_key=os.environ['DATADOG_API_KEY'],
    app_key=os.environ['DATADOG_APP_KEY'],
    statsd_constant_tags=[
        f"env:{os.environ.get('ENVIRONMENT', 'development')}",
        f"service:{os.environ.get('SERVICE_NAME', 'unknown')}",
        f"version:{os.environ.get('SERVICE_VERSION', '1.0.0')}",
        f"region:{os.environ.get('AWS_REGION', 'us-east-1')}",
        f"instance_type:{os.environ.get('INSTANCE_TYPE', 'unknown')}"
    ]
)

Install with Tessl CLI