Stackdriver Logging Client - Class LoggingClient (1.25.5)

Reference documentation and code samples for the Stackdriver Logging Client class LoggingClient.

Google Stackdriver Logging allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud Platform and Amazon Web Services. Find more information at the Google Stackdriver Logging docs.

This client supports transport over REST or gRPC.

In order to enable gRPC support please make sure to install and enable the gRPC extension through PECL:

$ pecl install grpc
```php

NOTE: Support for gRPC is currently at an Alpha quality level, meaning it is still
a work in progress and is more likely to get backwards-incompatible updates.

When using gRPC in production environments, it is highly recommended that you make use of the
Protobuf PHP extension for improved performance. Protobuf can be installed
via [PECL](https://pecl.php.net).

$ pecl install protobuf


Example:

use Google\Cloud\Logging\LoggingClient;

$logging = new LoggingClient();

Methods

psrBatchLogger

Create a PsrLogger with batching enabled.

Parameters
Name	Description
`name`	`string` The name of the log to write entries to.
`options`	`array` Configuration options.
`↳ apiEndpoint`	`string` A hostname with optional port to use in place of the service's default endpoint.
`↳ messageKey`	`string` The key in the `jsonPayload` used to contain the logged message. Defaults to `message`.
`↳ resource`	`array` The monitored resource to associate log entries with. Defaults to type global.
`↳ labels`	`array` A set of user-defined (key, value) data that provides additional information about the log entry.
`↳ metadataProvider`	`MetadataProviderInterface` Defaults to An automatically chosen provider, based on detected environment settings.
`↳ debugOutput`	`bool` Whether or not to output debug information. Please note debug output currently only applies in CLI based applications. Defaults to `false`.
`↳ batchOptions`	`array` A set of options for a BatchJob. Google\Cloud\Core\Batch\BatchJob::__construct() for more details. Defaults to ['batchSize' => 1000, 'callPeriod' => 2.0, 'numWorkers' => 2].
`↳ clientConfig`	`array` Configuration options for the Logging client used to handle processing of batch items. For valid options please see Google\Cloud\Logging\LoggingClient::__construct().
`↳ batchRunner`	`BatchRunner` A BatchRunner object. Mainly used for the tests to inject a mock. Defaults to a newly created BatchRunner.
`↳ closureSerializer`	`ClosureSerializerInterface` An implementation responsible for serializing closures used in the `$clientConfig`. This is especially important when using the batch daemon. Defaults to Google\Cloud\Logging\Google\Cloud\Core\Batch\OpisClosureSerializer if the `opis/closure` library is installed.

Returns
Type	Description
`Google\Cloud\Logging\PsrLogger`

__construct

Create a Logging client.

Parameters
Name	Description
`config`	`array` Configuration options.
`↳ projectId`	`string` The project ID from the Google Developer's Console.
`↳ authCache`	`CacheItemPoolInterface` A cache for storing access tokens. Defaults to a simple in memory implementation.
`↳ authCacheOptions`	`array` Cache configuration options.
`↳ authHttpHandler`	`callable` A handler used to deliver Psr7 requests specifically for authentication.
`↳ credentialsFetcher`	`FetchAuthTokenInterface` A credentials fetcher instance.
`↳ httpHandler`	`callable` A handler used to deliver Psr7 requests. Only valid for requests sent over REST.
`↳ keyFile`	`array` The contents of the service account credentials .json file retrieved from the Google Developer's Console. Ex: `json_decode(file_get_contents($path), true)`.
`↳ keyFilePath`	`string` The full path to your service account credentials .json file retrieved from the Google Developers Console.
`↳ requestTimeout`	`float` Seconds to wait before timing out the request. Defaults to `0` with REST and `60` with gRPC.
`↳ retries`	`int` Number of retries for a failed request. Defaults to `3`.
`↳ scopes`	`array` Scopes to be used for the request.
`↳ quotaProject`	`string` Specifies a user project to bill for access charges associated with the request.
`↳ transport`	`string` The transport type used for requests. May be either `grpc` or `rest`. Defaults to `grpc` if gRPC support is detected on the system.

createSink

Create a sink.

Example:

$sink = $logging->createSink('my-sink', 'storage.googleapis.com/my-bucket');

Parameters
Name	Description
`name`	`string` The name of the sink.
`destination`	`string` The export destination. Please see Exporting Logs With Sinks for more information and examples.
`options`	`array` Configuration options.
`↳ filter`	`string` An advanced logs filter.
`↳ outputVersionFormat`	`string` The log entry version to use for this sink's exported log entries. This version does not have to correspond to the version of the log entry when it was written to Stackdriver Logging. May be either `V1` or `V2`. Defaults to `V2`.

Returns
Type	Description
`Google\Cloud\Logging\Sink`

sink

Lazily instantiates a sink. There are no network requests made at this point. To see the operations that can be performed on a sink please see Google\Cloud\Logging\Sink.

Example:

$sink = $logging->sink('my-sink');
echo $sink->name();

Parameter
Name	Description
`name`	`string` The name of the sink.

Returns
Type	Description
`Google\Cloud\Logging\Sink`

sinks

Fetches sinks associated with your project.

Example:

$sinks = $logging->sinks();

foreach ($sinks as $sink) {
    echo $sink->name() . PHP_EOL;
}

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ pageSize`	`int` The maximum number of results to return per request.
`↳ resultLimit`	`int` Limit the number of results returned in total. Defaults to `0` (return all results).
`↳ pageToken`	`string` A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\logging\sink>`

createMetric

Create a metric.

Example:

$metric = $logging->createMetric(
    'my-metric',
    'logName = projects/my-project/logs/my-log'
);

Parameters
Name	Description
`name`	`string` The name of the metric.
`filter`	`string` An advanced logs filter.
`options`	`array` Configuration Options.
`↳ description`	`string` A description of the metric.

Returns
Type	Description
`Google\Cloud\Logging\Metric`

metric

Lazily instantiates a metric. There are no network requests made at this point. To see the operations that can be performed on a metric please see Google\Cloud\Logging\Metric.

Example:

$metric = $logging->metric('my-metric');
echo $metric->name();

Parameter
Name	Description
`name`	`string` The name of the metric.

Returns
Type	Description
`Google\Cloud\Logging\Metric`

metrics

Fetches metrics associated with your project.

Example:

$metrics = $logging->metrics();

foreach ($metrics as $metric) {
    echo $metric->name() . PHP_EOL;
}

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ pageSize`	`int` The maximum number of results to return per request.
`↳ resultLimit`	`int` Limit the number of results returned in total. Defaults to `0` (return all results).
`↳ pageToken`	`string` A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\logging\metric>`

entries

Fetches log entries.

Example:

$entries = $logging->entries();

foreach ($entries as $entry) {
    echo $entry->info()['textPayload'] . PHP_EOL;
}

// Use an advanced logs filter to fetch only entries from a specified log.
$entries = $logging->entries([
    'filter' => 'logName = projects/my-project/logs/my-log'
]);

foreach ($entries as $entry) {
    echo $entry->info()['textPayload'] . PHP_EOL;
}

Parameters
Name	Description
`options`	`array` Configuration options.
`↳ projectIds`	`string[]` A list of projectIds to fetch entries from in addition to entries found in the project bound to this client.
`↳ resourceNames`	`string[]` One or more cloud resources from which to retrieve log entries. Projects listed in projectIds are added to this list. Example: "projects/my-project-1A", "projects/1234567890".
`↳ filter`	`string` An advanced logs filter.
`↳ orderBy`	`string` How the results should be sorted. Presently, the only permitted values are `timestamp asc` and `timestamp desc`. Defaults to `"timestamp asc"`.
`↳ pageSize`	`int` The maximum number of results to return per request.
`↳ resultLimit`	`int` Limit the number of results returned in total. Defaults to `0` (return all results).
`↳ pageToken`	`string` A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\logging\entry>`

psrLogger

Fetches a logger which will write log entries to Stackdriver Logging and implements the PSR-3 specification.

Example:

$psrLogger = $logging->psrLogger('my-log');

// Write entries with background batching.
$psrLogger = $logging->psrLogger('my-log', [
    'batchEnabled' => true
]);

Parameters
Name	Description
`name`	`string` The name of the log to write entries to.
`options`	`array` Configuration options.
`↳ messageKey`	`string` The key in the `jsonPayload` used to contain the logged message. Defaults to `message`.
`↳ resource`	`array` The monitored resource to associate log entries with. Defaults to type global.
`↳ labels`	`array` A set of user-defined (key, value) data that provides additional information about the log entry.
`↳ metadataProvider`	`MetadataProviderInterface` Defaults to An automatically chosen provider, based on detected environment settings.
`↳ batchEnabled`	`bool` Determines whether or not to use background batching. Defaults to `false`.
`↳ debugOutput`	`bool` Whether or not to output debug information. Please note debug output currently only applies in CLI based applications. Defaults to `false`. Applies only when `batchEnabled` is set to `true`.
`↳ debugOutputResource`	`resource` A resource to output debug output to. Applies only when `batchEnabled` is set to `true`.
`↳ batchOptions`	`array` A set of options for a BatchJob. Google\Cloud\Core\Batch\BatchJob::__construct() for more details. Defaults to ['batchSize' => 1000, 'callPeriod' => 2.0, 'numWorkers' => 2]. Applies only when `batchEnabled` is set to `true`. Note that this option is currently considered experimental and is subject to change.
`↳ clientConfig`	`array` Configuration options for the Logging client used to handle processing of batch items. For valid options please see Google\Cloud\Logging\LoggingClient::__construct(). Defaults to the options provided to the current client. Applies only when `batchEnabled` is set to `true`.
`↳ batchRunner`	`BatchRunner` A BatchRunner object. Mainly used for the tests to inject a mock. Defaults to a newly created BatchRunner. Applies only when `batchEnabled` is set to `true`.
`↳ closureSerializer`	`ClosureSerializerInterface` An implementation responsible for serializing closures used in the `$clientConfig`. This is especially important when using the batch daemon. Defaults to Google\Cloud\Logging\Google\Cloud\Core\Batch\OpisClosureSerializer if the `opis/closure` library is installed.

Returns
Type	Description
`Google\Cloud\Logging\PsrLogger`

logger

Fetches a logger which will write log entries to Stackdriver Logging.

Example:

$logger = $logging->logger('my-log');

Parameters
Name	Description
`name`	`string` The name of the log to write entries to.
`options`	`array` Configuration options.
`↳ resource`	`array` The monitored resource to associate log entries with. Defaults to type global.
`↳ labels`	`array` A set of user-defined (key, value) data that provides additional information about the log entry.

Returns
Type	Description
`Google\Cloud\Logging\Logger`

Constants

VERSION

Value: '1.25.5'

FULL_CONTROL_SCOPE

Value: 'https://www.googleapis.com/auth/logging.admin'

READ_ONLY_SCOPE

Value: 'https://www.googleapis.com/auth/logging.read'

WRITE_ONLY_SCOPE

Value: 'https://www.googleapis.com/auth/logging.write'