PHPackages                             garbetjie/monolog-bigquery-handler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. garbetjie/monolog-bigquery-handler

ActiveLibrary[Logging & Monitoring](/categories/logging)

garbetjie/monolog-bigquery-handler
==================================

A configurable Monolog handler for writing logs to BigQuery.

v1.4.0(7y ago)0386MITPHPPHP >=7.0

Since Aug 25Pushed 7y ago1 watchersCompare

[ Source](https://github.com/garbetjie/monolog-bigquery-handler)[ Packagist](https://packagist.org/packages/garbetjie/monolog-bigquery-handler)[ Docs](https://github.com/garbetjie/monolog-bigquery-handler)[ RSS](/packages/garbetjie-monolog-bigquery-handler/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (2)Versions (6)Used By (0)

BigQuery Monolog Handler
========================

[](#bigquery-monolog-handler)

A simple (and configurable) Monolog handler for writing log messages to BigQuery, making use of Google's `google/cloud-bigquery` PHP client.

Installation
------------

[](#installation)

```
composer require garbetjie/monolog-bigquery-handler

```

Requires PHP 7.0.

Getting started
---------------

[](#getting-started)

The handler expects the BigQuery dataset and table to have been created already - the handler will not create either of them.

You can run the following command (using the BigQuery command line tool) to create a minimal table that will be able to accept log records (replace `$dataset` and `$table` with the actual dataset and table names):

```
bq mk --schema="channel:string,message:string,level:integer,level_name:string,context:string,extra:string,datetime:timestamp" --time_partitioning_field="datetime" "$dataset.$table"
```

Usage
-----

[](#usage)

Simply create an instance of the BigQuery client, and pass it to the handler, along with the dataset and table names to insert log records to.

```
$bigQueryClient = new Google\Cloud\BigQuery\BigQueryClient();
$handler = new Garbetjie\Monolog\Handler\BigQueryHandler($bigQueryClient, 'dataset_name', 'table_name', $level = Logger::DEBUG, $bubble = true);
$logger = new Monolog\Logger('channel', [$handler]);

$logger->debug('debug message');
```

The usage shown above will send each message individually. It is recommended to make use of a `BufferHandler`. This will ensure that log messages are batched, and will reduce the duration spent sending log messages.

When determining the size of the buffer to use, ensure that you're aware of the [quota limits for streaming inserts](https://cloud.google.com/bigquery/quotas#streaming_inserts)in BigQuery. If any of these limits are hit, the whole batch of messages will fail.

An example of using the `BufferHandler` is shown below:

```
// Using a buffer handler to batch log messages.

$bigQueryClient = new Google\Cloud\BigQuery\BigQueryClient();
$handler = new Garbetjie\Monolog\Handler\BigQueryHandler($bigQueryClient, 'dataset_name', 'table_name', $level = Logger::DEBUG, $bubble = true);
$handler = new Monolog\Handler\BufferHandler($handler, $bufferLimit = 10);
$logger = new Monolog\Logger('channel', [$handler]);

$logger->debug('message 1');
$logger->debug('message 2');
$logger->debug('message 3');
```

### Custom fields

[](#custom-fields)

Additional custom fields can be sent along with the logged fields. These custom fields can be added in the following way:

```
// Using custom fields

$handler = new Garbetjie\Monolog\Handler\BigQueryHandler($bigQueryClient, 'dataset_name', 'table_name', $level = Logger::DEBUG, $bubble = true);

$handler->setCustomField('field_name', 'field_value');
// Or $handler->setCustomField(['name' => 'value', 'other_name' => 'other_value'])

$handler->removeCustomField('field_name');
// Or $handler->removeCustomField(['field_name', 'other_field_name']);
```

Custom field values can be any scalar value that can be JSON encoded, or one of the following values:

- **`callable`:** Any `callable` can be passed, and it will be executed before the log record is sent to BigQuery.

### Mapping fields

[](#mapping-fields)

By default, the field names to insert to are the same as the [structure of a log record](https://github.com/Seldaek/monolog/blob/334b8d8783a1262c3b8311d6599889d82e9cc58c/doc/message-structure.md). However, if you have BigQuery column names that aren't the same as these, you can map the log record field names to your own column names:

```
$bigQueryClient = new Google\Cloud\BigQuery\BigQueryClient();
$handler = new Garbetjie\Monolog\Handler\BigQueryHandler($bigQueryClient, 'dataset_name', 'table_name', $level = Logger::DEBUG, $bubble = true);
$handler->setFieldMapping(['datetime' => 'logged_at']);  // The `datetime` log record field will now be saved to the `logged_at` column.

$logger->debug('message 1');
```

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

5

Last Release

2804d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4f9a85f8c9c284a8e8e409583ed2ce79c73a5936fd4978f1d4f51492d2894149?d=identicon)[garbetjie](/maintainers/garbetjie)

---

Top Contributors

[![garbetjie](https://avatars.githubusercontent.com/u/254752?v=4)](https://github.com/garbetjie "garbetjie (14 commits)")

---

Tags

bigqueryloggingmonologmonolog-handlerlogloggingmonologbigquery

### Embed Badge

![Health badge](/badges/garbetjie-monolog-bigquery-handler/health.svg)

```
[![Health](https://phpackages.com/badges/garbetjie-monolog-bigquery-handler/health.svg)](https://phpackages.com/packages/garbetjie-monolog-bigquery-handler)
```

###  Alternatives

[inpsyde/wonolog

Monolog-based logging package for WordPress.

183617.9k7](/packages/inpsyde-wonolog)[logtail/monolog-logtail

Logtail handler for Monolog

233.2M3](/packages/logtail-monolog-logtail)[inpsyde/logzio-monolog

Logz.io integration for Monolog

191.2M1](/packages/inpsyde-logzio-monolog)[mero/yii2-monolog

The Monolog integration for the Yii framework.

42186.1k](/packages/mero-yii2-monolog)[mero/telegram-handler

Monolog handler to send log by Telegram

36113.3k](/packages/mero-telegram-handler)[lefuturiste/monolog-discord-handler

A simple monolog handler for support Discord webhooks

34111.6k4](/packages/lefuturiste-monolog-discord-handler)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)