Google.Cloud.Logging.Log4Net - Class GoogleStackdriverAppender (4.1.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

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.

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
TypeDescription
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
TypeDescription
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
TypeDescription
bool

DisposeTimeoutSeconds

public int DisposeTimeoutSeconds { get; set; }

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

Property Value
TypeDescription
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
TypeDescription
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
TypeDescription
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
TypeDescription
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
TypeDescription
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
TypeDescription
long

MaxUploadBatchSize

public int MaxUploadBatchSize { get; set; }

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

Property Value
TypeDescription
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
TypeDescription
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
TypeDescription
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
TypeDescription
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
TypeDescription
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
TypeDescription
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
TypeDescription
bool

Methods

ActivateOptions()

public override void ActivateOptions()
Overrides
log4net.Appender.AppenderSkeleton.ActivateOptions()

AddCustomLabel(Label)

public void AddCustomLabel(GoogleStackdriverAppender.Label label)

Specify custom labels for all log entries.

Parameter
NameDescription
labelGoogleStackdriverAppenderLabel

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
NameDescription
labelGoogleStackdriverAppenderLabel

The resource type label.

AddWithMetaData(MetaDataType)

public void AddWithMetaData(MetaDataType enable)

Specify additional metadata to include in all log entries.

Parameter
NameDescription
enableMetaDataType

The additional metadata to enable.

Append(LoggingEvent)

protected override void Append(LoggingEvent loggingEvent)
Parameter
NameDescription
loggingEventlog4net.Core.LoggingEvent
Overrides
log4net.Appender.AppenderSkeleton.Append(log4net.Core.LoggingEvent)

Append(LoggingEvent[])

protected override void Append(LoggingEvent[] loggingEvents)
Parameter
NameDescription
loggingEventslog4net.Core.LoggingEvent
Overrides
log4net.Appender.AppenderSkeleton.Append(log4net.Core.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
NameDescription
millisecondsTimeoutint

The maxmimum time in milliseconds to spend waiting for the flush to complete.

Returns
TypeDescription
bool

Whether the flush completed within the timeout.

Overrides

Flush(TimeSpan, CancellationToken)

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

Flush locally buffered log entries to the server.

Parameters
NameDescription
timeoutTimeSpan

The maxmimum time to spend waiting for the flush to complete.

cancellationTokenCancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns
TypeDescription
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
NameDescription
timeoutTimeSpan

The maxmimum time to spend waiting for the flush to complete.

cancellationTokenCancellationToken

The token to monitor for cancellation requests. The default value is None.

Returns
TypeDescription
Taskbool

A task representing whether the flush completed within the timeout.

OnClose()

protected override void OnClose()
Overrides
log4net.Appender.AppenderSkeleton.OnClose()