Weave Code
Monolog Handler Laravel Package
app-insights-php/monolog-handler
Monolog handlers for Microsoft Application Insights: send traces and dependency telemetry via AppInsightsTraceHandler and AppInsightsDependencyHandler. Supports buffering for long-running workers and enforces the 64KB telemetry size limit. Includes Laravel setup example.
Microsoft App Insights monolog handler for trace tracking
Frequently asked questions about Monolog Handler
- How do I integrate this package with Laravel’s logging system?
- Add the handler to your `config/logging.php` under a new channel (e.g., `appinsights`) with the `AppInsightsTraceHandler` class. Then register a service provider to bind the handler with your Azure instrumentation key. The README provides a step-by-step Laravel setup example.
- Which Laravel versions are supported by this package?
- This package works with Laravel 8, 9, and 10, as it relies on Monolog v2+, which is compatible with all these versions. Ensure your `composer.json` specifies Monolog v2+ as a dependency.
- Can I use this for dependency tracking (e.g., database queries, HTTP calls)?
- Yes, the package includes an `AppInsightsDependencyHandler` specifically for tracking dependencies like database calls or external HTTP requests. Configure it alongside the trace handler in your Monolog setup.
- What happens if my logs exceed Azure App Insights’ 64KB telemetry limit?
- The handler automatically checks telemetry size before sending. If a log entry would exceed 64KB, it’s discarded to prevent failures. Always maintain a secondary logging solution (e.g., file or database) to avoid data loss.
- How do I handle long-running processes like queue workers or CLI jobs?
- Wrap the handler in Monolog’s `BufferHandler` to batch logs and flush them periodically. This prevents memory issues and ensures telemetry is sent even for processes running longer than the default flush interval.
- Does this package support custom properties or dimensions in App Insights?
- Yes, you can attach custom properties or dimensions to logs using the `ContextFlatterFormatter` or by modifying the telemetry context directly via the `Telemetry_Client` before logging. Refer to the Azure SDK documentation for available options.
- Is there a way to test this handler without sending real logs to Azure?
- Mock the `Telemetry_Client` in your unit tests to verify logs are routed correctly. For end-to-end testing, use Azure’s test instrumentation key or a local sandbox environment to validate telemetry appears as expected.
- Can I use this alongside other Monolog handlers (e.g., single, syslog)?
- Absolutely. The handler integrates seamlessly with Laravel’s stack channel or custom Monolog configurations. Add it to your `logging.php` alongside other handlers, and logs will be processed by all configured handlers in sequence.
- What are the alternatives if I need vendor-agnostic observability?
- For broader compatibility, consider OpenTelemetry PHP (e.g., `open-telemetry/php`) or packages like `spatie/laravel-monitoring`. These support multiple backends, including App Insights, but require additional setup for distributed tracing.
- How do I handle sensitive data (PII) in logs before sending to App Insights?
- Use Monolog’s `Processor` interface to filter or mask sensitive data before it reaches the handler. For example, create a custom processor to redact tokens or personal information from log contexts before they’re sent to Azure.
Weaver
How can I help you explore Laravel packages today?