Google.Cloud.Logging.Log4Net - Class GoogleStackdriverAppender (4.4.0)

public sealed class GoogleStackdriverAppender : AppenderSkeleton, IBulkAppender, IAppender, IOptionHandler, IFlushable, IDisposable

Reference documentation and code samples for the Google.Cloud.Logging.Log4Net class GoogleStackdriverAppender.

Appends logging events to Google Stackdriver Logging.

Inheritance

object > log4net.Appender.AppenderSkeleton > GoogleStackdriverAppender

Implements

log4net.Appender.IBulkAppender, log4net.Appender.IAppender, log4net.Core.IOptionHandler, log4net.Appender.IFlushable, IDisposable

Inherited Members

log4net.Appender.AppenderSkeleton.Close()

log4net.Appender.AppenderSkeleton.DoAppend(log4net.Core.LoggingEvent)

log4net.Appender.AppenderSkeleton.DoAppend(log4net.Core.LoggingEvent[])

log4net.Appender.AppenderSkeleton.AddFilter(log4net.Filter.IFilter)

log4net.Appender.AppenderSkeleton.ClearFilters()

log4net.Appender.AppenderSkeleton.Threshold

log4net.Appender.AppenderSkeleton.ErrorHandler

log4net.Appender.AppenderSkeleton.FilterHead

log4net.Appender.AppenderSkeleton.Layout

log4net.Appender.AppenderSkeleton.Name

object.GetHashCode()

object.GetType()

object.ToString()

Namespace

Google.Cloud.Logging.Log4Net

Assembly

Google.Cloud.Logging.Log4Net.dll

Remarks

Logging events are sent to Google Stackdriver Logging asychronously, via a local buffer. This is to ensure that server errors or increased network/server latency don't cause slow-downs in the program being logged.

GoogleStackdriverAppender provides two methods of flushing this local buffer.

The Flush(TimeSpan, CancellationToken) and FlushAsync(TimeSpan, CancellationToken) flush local buffer entries to Google Stackdriver, waiting a maximum of the specified TimeSpan. These methods return true if all locally buffered entries were successfully flushed, or false otherwise.
GoogleStackdriverAppender implements IDisposable. This calls Flush(TimeSpan, CancellationToken) with the timeout configured in DisposeTimeoutSeconds, then closes the appender so no further logging can be performed. It is not generally necessary to call Dispose().

Constructors

GoogleStackdriverAppender()

public GoogleStackdriverAppender()

Construct a Google Stackdriver appender.

Properties

CredentialFile

public string CredentialFile { get; set; }

The file path of a service account JSON file to use for authentication. Not necessary if running on GCE or GAE or if the GOOGLE_APPLICATION_CREDENTIALS environment variable has been set. Must not be set if CredentialJson is set.

Property Value
Type	Description
`string`

CredentialJson

public string CredentialJson { get; set; }

JSON credential for authentication. Not necessary if running on GCE or GAE or if the GOOGLE_APPLICATION_CREDENTIALS environment variable has been set. Must not be set if CredentialFile is set.

Property Value
Type	Description
`string`

DisableResourceTypeDetection

public bool DisableResourceTypeDetection { get; set; }

If set, disables resource-type detection based on platform, so ResourceType will default to "global" if not manually set.

Property Value
Type	Description
`bool`

DisposeTimeoutSeconds

public int DisposeTimeoutSeconds { get; set; }

The maximum time the Dispose() call of GoogleStackdriverAppender may take. Default value is 30 seconds.

Property Value
Type	Description
`int`

JsonLayout

public IJsonLayout JsonLayout { get; set; }

A "layout" to use to convert each logging event into a JSON payload. If this is null (the default), or if it returns a null JSON payload for a particular logging event, a text payload is used instead.

Property Value
Type	Description
`IJsonLayout`

LocalQueueType

public LocalQueueType LocalQueueType { get; set; }

The local queuing mechanism, used before the log is sent to Google Logging. Defaults to Memory.

Property Value
Type	Description
`LocalQueueType`

Remarks

All log entries are temporarily queued locally before being uploaded to Google Logging. This is usually for a very brief duration; but if there are problems connecting to Google Logging this local queue allows the application to continue functioning as normal, without blocking on log events or immediately throwing aware log entries.

One queue type is provided:

Memory: Log entries are queued locally in memory. The maximum amount of memory and/or the maximum number of log entries to queue can be configured. If the application exits or crashes before in-memory log entries have been uploaded to Google Logging, then these log entries are permanently lost. If Google Logging becomes temporarily unavailable then the number of log entries queued until Google Logging becomes available again will be limited by the configure maximum sizes; log entries in excess of this configured maximum will cause the oldest queued log entries to be permanently lost.

LogId

public string LogId { get; set; }

LogID for all log entries. Must be configured.

Property Value
Type	Description
`string`

MaxMemoryCount

public int MaxMemoryCount { get; set; }

The maximum count of log entries allowed in the in-memory logging queue. Default value is 1,000 Not used for file-based queueing.

Property Value
Type	Description
`int`

MaxMemorySize

public long MaxMemorySize { get; set; }

The maximum bytes of memory used by in-memory logging queue. Default value is 0 (unconfigured). Not used for file-based queuing.

Property Value
Type	Description
`long`

MaxUploadBatchSize

public int MaxUploadBatchSize { get; set; }

The maximum batch size when uploading to Google Cloud Logging. Default value is 100.

Property Value
Type	Description
`int`

ProjectId

public string ProjectId { get; set; }

The project ID for all log entries. Must be configured in not executing on Google Compute Engine or Google App Engine. If running on GCE or GAE, the ProjectId will be automatically detected if not set.

Property Value
Type	Description
`string`

ResourceType

public string ResourceType { get; set; }

The resource type of log entries. Default value depends on the detected platform. See the remarks section for details.

Property Value
Type	Description
`string`

Remarks

If this is not set, then Resource type is set depending on the detected execution platform:

Google App Engine: ResourceType "gae_app", with project_id, module_id, and version_id set approprately.
Google Compute Engine: ResourceType "gce_instance", with project_id, instance_id, and zone set approprately.
Unknown: ResourceType "global", with project_id set from this configuration.

If DisableResourceTypeDetection is true, then this platform detection is not performed, and this ResourceType defaults to "global" if not set.

ServerErrorBackoffDelaySeconds

public int ServerErrorBackoffDelaySeconds { get; set; }

On receiving a server error during log upload, the initial delay in seconds before retry. Defaults value is 1 second.

Property Value
Type	Description
`int`

ServerErrorBackoffMaxDelaySeconds

public int ServerErrorBackoffMaxDelaySeconds { get; set; }

The maxmimum retry delay when receiving multiple consecutive server errors during log upload. Default value is 60 seconds.

Property Value
Type	Description
`int`

ServerErrorBackoffMultiplier

public double ServerErrorBackoffMultiplier { get; set; }

The multiplier applied to the retry delay when receiving multiple consecutive server errors during log upload. Default value is 1.5

Property Value
Type	Description
`double`

UsePatternWithinCustomLabels

public bool UsePatternWithinCustomLabels { get; set; }

Enables PatternLayout use in custom labels. All the standard patterns documented in for Log4Net PatternLayout are available. Custom pattern conversions are not possible.

Property Value
Type	Description
`bool`

Methods

ActivateOptions()

public override void ActivateOptions()

Initialize the appender based on the options set

Overrides

log4net.Appender.AppenderSkeleton.ActivateOptions()

Remarks

This is part of the log4net.Core.IOptionHandler delayed object activation scheme. The log4net.Appender.AppenderSkeleton.ActivateOptions() method must be called on this object after the configuration properties have been set. Until log4net.Appender.AppenderSkeleton.ActivateOptions() is called this object is in an undefined state and must not be used.

If any of the configuration properties are modified then log4net.Appender.AppenderSkeleton.ActivateOptions() must be called again.

AddCustomLabel(Label)

public void AddCustomLabel(GoogleStackdriverAppender.Label label)

Specify custom labels for all log entries.

Parameter
Name	Description
`label`	`GoogleStackdriverAppenderLabel` The custom label.

AddResourceLabel(Label)

public void AddResourceLabel(GoogleStackdriverAppender.Label label)

Specify labels for the resource type; only used if platform detection is disabled or detects an unknown platform.

Parameter
Name	Description
`label`	`GoogleStackdriverAppenderLabel` The resource type label.

AddWithMetaData(MetaDataType)

public void AddWithMetaData(MetaDataType enable)

Specify additional metadata to include in all log entries.

Parameter
Name	Description
`enable`	`MetaDataType` The additional metadata to enable.

Append(LoggingEvent)

protected override void Append(LoggingEvent loggingEvent)

Subclasses of log4net.Appender.AppenderSkeleton should implement this method to perform actual logging.

Parameter
Name	Description
`loggingEvent`	`log4net.Core.LoggingEvent` The event to append.

Overrides

log4net.Appender.AppenderSkeleton.Append(log4net.Core.LoggingEvent)

Remarks

A subclass must implement this method to perform logging of the loggingEvent.

This method will be called by DoAppend(LoggingEvent) if all the conditions listed for that method are met.

To restrict the logging of events in the appender override the PreAppendCheck() method.

Append(LoggingEvent[])

protected override void Append(LoggingEvent[] loggingEvents)

Append a bulk array of logging events.

Parameter
Name	Description
`loggingEvents`	`log4net.Core.LoggingEvent` the array of logging events

Overrides

log4net.Appender.AppenderSkeleton.Append(log4net.Core.LoggingEvent[])

Remarks

This base class implementation calls the Append(LoggingEvent) method for each element in the bulk array.

A sub class that can better process a bulk array of events should override this method in addition to Append(LoggingEvent).

Dispose()

public void Dispose()

Dispose of this appender, by flushing locally buffer entries then closing the appender.

Remarks

The flush timeout is configured using the DisposeTimeoutSeconds configuration option. This defaults to 30 seconds if not set.

Flush(int)

public override bool Flush(int millisecondsTimeout)

Flush locally buffered log entries to the server.

Parameter
Name	Description
`millisecondsTimeout`	`int` The maxmimum time in milliseconds to spend waiting for the flush to complete.

Returns
Type	Description
`bool`	Whether the flush completed within the timeout.

Overrides

AppenderSkeleton.Flush(int)

Flush(TimeSpan, CancellationToken)

public bool Flush(TimeSpan timeout, CancellationToken cancellationToken = default)

Flush locally buffered log entries to the server.

Parameters
Name	Description
`timeout`	`TimeSpan` The maxmimum time to spend waiting for the flush to complete.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests. The default value is None.

Returns
Type	Description
`bool`	Whether the flush completed within the timeout.

FlushAsync(TimeSpan, CancellationToken)

public Task<bool> FlushAsync(TimeSpan timeout, CancellationToken cancellationToken = default)

Flush locally buffered log entries to the server.

Parameters
Name	Description
`timeout`	`TimeSpan` The maxmimum time to spend waiting for the flush to complete.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests. The default value is None.

Returns
Type	Description
`Taskbool`	A task representing whether the flush completed within the timeout.

OnClose()

protected override void OnClose()

Is called when the appender is closed. Derived classes should override this method if resources need to be released.

Overrides

log4net.Appender.AppenderSkeleton.OnClose()

Remarks

Releases any resources allocated within the appender such as file handles, network connections, etc.

It is a programming error to append to a closed appender.