shadowbane/laravel-datadog-logger
| Install | |
|---|---|
composer require shadowbane/laravel-datadog-logger |
|
| Latest Version: | v2.0.0 |
| PHP: | ^8.1 || ^8.2 || ^8.3 || ^8.4 |
| Laravel: | 10 – 13 |
| License: | MIT |
| Last Updated: | Nov 12, 2026 |
| Links: | GitHub · Packagist |
Laravel DataDog Logger
A custom Laravel Monolog logger for sending logs to DataDog via their HTTP API.
Features
- Send Laravel logs directly to DataDog via HTTP API
- Non-blocking by default: logs are batched and sent after the response
- Automatic exception tracking with stack traces
- Custom log context support
- Configurable log levels and endpoints
- Error reporting for failed API requests
- Environment-based tagging
Requirements
- PHP ^8.1 || ^8.2 || ^8.3 || ^8.4
- Laravel 10.x or higher
- ext-json
- ext-curl
- Guzzle ^6.0 || ^7.0 || ^8.0
- Monolog ^3.0
Installation
Install the package via Composer:
composer require shadowbane/laravel-datadog-logger
The service provider will be automatically registered.
Configuration
Environment Variables
Add the following to your .env file:
DATADOG_API_KEY=your-datadog-api-key
DATADOG_LEVEL=warning
DATADOG_BUBBLE=true
DATADOG_ENVIRONMENT=production
DATADOG_API_ENDPOINT=https://http-intake.logs.datadoghq.com/api/v2/logs
DATADOG_ERROR_LOG_CHANNEL=stack
DATADOG_BUFFER=true
DATADOG_TIMEOUT=2
Configuration Options
| Variable | Description | Default |
|---|---|---|
DATADOG_API_KEY |
Your DataDog API key (required) | - |
DATADOG_LEVEL |
Minimum log level (debug, info, notice, warning, error, critical, alert, emergency) | warning |
DATADOG_BUBBLE |
Whether logs should bubble to other handlers | true |
DATADOG_ENVIRONMENT |
Environment tag for DataDog | Laravel's app()->environment() |
DATADOG_API_ENDPOINT |
DataDog logs API endpoint | https://http-intake.logs.datadoghq.com/api/v2/logs |
DATADOG_ERROR_LOG_CHANNEL |
Laravel log channel for logging DataDog API failures | false |
DATADOG_BUFFER |
Batch logs and send them after the response instead of one blocking request per log line | true |
DATADOG_TIMEOUT |
Seconds to wait for DataDog (connect and total) before giving up | 2 |
How logs are delivered
With DATADOG_BUFFER=true (the default), log calls return immediately. Records are held in memory and sent in one batch request:
- HTTP (php-fpm): at shutdown, after the response has been sent to the client, so users never wait on DataDog.
- Queue workers: after each job (
JobProcessed,JobExceptionOccurred,JobFailed), because a worker process does not shut down between jobs. - Console commands: when the command terminates.
- Large requests: early, once 1000 records are buffered.
Batches are split to stay within DataDog's limits of 1000 entries and 5MB per request. Records still in memory when a process is hard-killed (SIGKILL, out-of-memory) are lost; set DATADOG_BUFFER=false to send each record synchronously as it is logged.
Laravel Logging Configuration
The package automatically merges the datadog-api channel into your logging configuration. You can use it in your config/logging.php:
'channels' => [
'stack' => [
'driver' => 'stack',
'channels' => ['single', 'datadog-api'],
],
]
Usage
Basic Logging
Use the datadog-api channel to send logs to DataDog:
use Illuminate\Support\Facades\Log;
Log::channel('datadog-api')->info('User logged in', [
'user_id' => 123,
'ip_address' => '192.168.1.1',
]);
Log::channel('datadog-api')->error('Payment failed', [
'order_id' => 456,
'amount' => 99.99,
]);
Exception Logging
When logging exceptions, pass the exception in the context array with the key exception:
try {
// Your code
} catch (\Exception $e) {
Log::channel('datadog-api')->error('Failed to create company: ' . $e->getMessage(), [
'exception' => $e,
'company_id' => 123,
'user_id' => 456,
]);
}
The logger will automatically extract:
- Exception message (becomes the message; falls back to the class name when the exception carries no message)
- Exception class (
error.kind) — group by@error.kindin DataDog - Error message (
error.message) - Stack trace (
error.stack), including the fullgetPrevious()chain - Source location (
error.file,error.line)
Anything implementing Throwable is handled, so PHP's Error hierarchy
(TypeError, ValueError, ArgumentCountError) is captured alongside Exception.
Wrapped exceptions are rendered in full, separated by Caused by:. This matters
because the outermost exception is often a generic wrapper, while the detail that
identifies the failure lives in the cause:
RuntimeException: Unable to complete request in /app/src/Client.php:88
#0 …
Caused by: PDOException: SQLSTATE[HY000] [2002] Connection refused in /app/src/Db.php:31
#0 …
Log Context
All context data (except exception, message, and messages) is sent to DataDog as custom attributes:
Log::channel('datadog-api')->warning('High memory usage', [
'memory_used' => '512MB',
'memory_limit' => '256MB',
'server' => 'web-01',
]);
This will create a log in DataDog with custom attributes: memory_used, memory_limit, and server.
Testing
Test your DataDog integration using the included Artisan command:
php artisan datadog:send-test-exception
This command sends a test exception to DataDog with sample context data.
Log Level Mapping
Laravel log levels are mapped to DataDog status levels:
| Laravel Level | DataDog Status |
|---|---|
| debug, info | info |
| notice, warning | warn |
| error, critical, alert, emergency | error |
Error Handling
If the DataDog API request fails, you can configure a fallback Laravel log channel to capture these errors:
DATADOG_ERROR_LOG_CHANNEL=stack
Failed API requests will be logged to this channel with the Guzzle exception details.
DataDog Log Structure
Logs sent to DataDog include the following fields:
ddsource: Always set tolaravelddtags: Environment tag (e.g.,env:production)hostname: Server hostnamemessage: Formatted log message (or the exception message when one is present)service: Your Laravel application name (fromconfig('app.name'))status: Mapped log level (info, warn, error)timestamp: Log timestamp in milliseconds- Custom attributes from log context
For throwables:
error.kind: Exception classerror.message: Exception messageerror.stack: Stack trace, including theCaused by:chainerror.file/error.line: Where it was thrownlogger.message: The message the application passed to the logger, when it differs from the exception message (e.g.Log::error('Charge failed for invoice #123', ['exception' => $e])). Search it with@logger.message:*invoice*.
Development
Static Analysis
Run PHPStan for static analysis:
vendor/bin/phpstan analyze
License
This package is open-sourced software licensed under the MIT license.
Credits
Support
If you discover any issues, please open an issue on the GitHub repository.
Related Packages
This Processor will display in the logs bread crumbs by which you can more quick...
A custom PHP array handler based on Laravel's Illuminate/Support/Arr class
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| v2.0.0 | ^8.1 || | ^10.0 || | MIT | |
| v1.3.0 | ^8.1 || | ^10.0 || | MIT | |
| v1.2.1 | ^8.1 || | MIT | ||
| v1.2.0 | ^8.1 || | MIT | ||
| v1.1.0 | ^8.1 || | MIT | ||
| v1.0 | ^8.1 || | MIT | ||
| v0.2.3 | ^7.4 || | MIT | ||
| v0.2.2 | ^7.4 || | MIT | ||
| v0.2.1 | ^7.4 || | MIT | ||
| v0.2 | ^7.4 || | MIT | ||
| v0.1.1 | ^7.4 || | MIT | ||
| v0.1 | ^7.4 || | MIT |