Google.Cloud.Logging.NLog

Google.Cloud.Logging.NLog is a .NET client library to integrate Google Stackdriver Logging with NLog.

Note: This documentation is for version 5.2.0 of the library. Some samples may not work with other versions.

Installation

Install the Google.Cloud.Logging.NLog package from NuGet. Add it to your project in the normal way (for example by right-clicking on the project in Visual Studio and choosing "Manage NuGet Packages...").

Authentication

When running on Google Cloud, no action needs to be taken to authenticate.

Otherwise, the simplest way of authenticating your API calls is to set up Application Default Credentials. The credentials will automatically be used to authenticate. See Set up Application Default Credentials for more details.

Getting started

Console app

Create an nlog configuration file (nlog.xml):

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <extensions>
    <add assembly="Google.Cloud.Logging.NLog" />
  </extensions>
  
  <targets async="true">
    <target name="stackdriver" xsi:type="GoogleStackdriver" projectId="PROJECT_ID" logId="LOG_ID">
      <!-- Potentially additional configuration -->
    </target>
    <target name="console" xsi:type="Console" />
  </targets>

  <rules>
    <logger name="*" minlevel="Info" writeTo="stackdriver" />
    <logger name="*" minlevel="Info" writeTo="console" />
  </rules>
  
</nlog>

Edit the file replacing PROJECT_ID with your Google Cloud Project ID, and LOG_ID with an identifier for your application.

Ensure the file is copied to the output directory. For example, in your project file you might include:

<None Update="nlog.xml" CopyToOutputDirectory="Always" />

Use this file to configure NLog and then log as normal:

// Configure nlog to use Google Stackdriver logging from the XML configuration file.
LogManager.Setup().LoadConfigurationFromFile("nlog.xml", optional: false);

// Acquire a logger for this class
Logger logger = LogManager.GetCurrentClassLogger();
// Log some information. This log entry will be sent to Google Stackdriver Logging.
logger.Info("An exciting log entry!");

// Flush buffered log entries before program exit; then shutdown the logger before program exit.
LogManager.Flush(TimeSpan.FromSeconds(15));
LogManager.Shutdown();

If executing on Google App Engine (GAE), Google Kubernetes Engine (GKE), or Google Compute Engine (GCE), then the projectId="PROJECT_ID" configuration setting can be omitted; it will be auto-detected from the platform at run-time.

Configuration options

  • ProjectId - Google Cloud project ID where logs will be sent to. Can be omitted if executing on on Google App Engine (GAE) or Google Compute Engine (GCE)
  • LogId - Name of log under the resource type (Default = "Default")
  • DisableResourceTypeDetection - Defaults to false. Setting this to true disables automatic resource type detection based on platform detection.
  • ResourceType - Resource type for logs. Must be one of the supported types listed in the cloud logging documentation. This is not needed if resource type detection is successful. If resource type detection fails or is disabled, and this is not set, the resource type in log entries is set to "global".
  • ResourceLabel - Used to specify extra labels as shown in the Monitoring Resource Types list.
  • ContextProperty - Allows custom labels to be added to the log entries as extra metadata.
  • CredentialFile - Credentials using a JSON file, instead of using the application default credentials
  • CredentialJson - Credentials using raw JSON input, instead of using the application default credentials
  • IncludeCallSite - Include LogEntrySourceLocation extracted from NLog callsite. (This only includes the function name.)
  • IncludeCallSiteStackTrace - Include LogEntrySourceLocation extracted from NLog callsite. (This also includes file name and line number.)
  • IncludeEventProperties - Includes structured logging properties from NLog LogEventInfo.Properties.
  • IncludeMdlc - Include async thread context properties from NLog MappedDiagnosticsLogicalContext
  • SendJsonPayload - Use the jsonPayload property in log entries instead of textPayload. When this is enabled, properties are set within the payload instead of as custom labels
  • ServiceContextName - Configures the "service" in "serviceContext" when sending a JSON payload. (Defaults to the AppDomain.FriendlyName of the running code.)
  • ServiceContextVersion - Configures the "version" in "serviceContext" when sending a JSON payload. (Defaults to the FileVersion of the entry assembly.)
  • EnableJsonLayout - Uses NLog's native JSON layout to format JSON payloads, completely replacing the default layout.
  • JsonConverter or JsonConverterTypeName/JsonConverterMethodName - Configures a custom conversion for individual values within a JSON payload.
  • TraceId - The trace ID to associate to log entries. Ex: 06796866738c859f2f19b7cfb3214824. See Google Logging V2 LogEntry reference docs for more information.
  • SpanId - The span ID within the trace associated with the log entry. Trace API v2 uses a 16-character hexadecimal encoding of an 8-byte array, ex: 000000000000004a. See Google Logging V2 LogEntry reference docs for more information.
  • TraceSampled - The sampling decision of the trace associated with the log entry. See Google Logging V2 LogEntry reference docs for more information.

Sending JsonPayload

Enabling SendJsonPayload will capture structured logging properties in JSON format (instead of saving them as resource labels).

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <extensions>
    <add assembly="Google.Cloud.Logging.NLog" />
  </extensions>
  
  <targets async="true">
    <target name="stackdriver" xsi:type="GoogleStackdriver" projectId="PROJECT_ID" logId="LOG_ID" includeEventProperties="true" sendJsonPayload="true">
      <contextproperty name="exception" layout="${exception:format=tostring}" />  <!-- Optional and repeatable -->
    </target>
    <target name="console" xsi:type="Console" />
  </targets>

  <rules>
    <logger name="*" minlevel="Info" writeTo="stackdriver" />
    <logger name="*" minlevel="Info" writeTo="console" />
  </rules>
  
</nlog>

Custom JsonPayload

Enabling EnableJsonLayout will override the standard JSON format, and instead depend on the output from NLog JsonLayout. This will completely replace the JSON payload, but has a performance penalty because of additional parsing.

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <extensions>
    <add assembly="Google.Cloud.Logging.NLog" />
  </extensions>
  
  <targets async="true">
    <target type="GoogleStackdriver" name="stackdriver"
            projectId="PROJECT_ID" logId="LOG_ID" resourceType="container" sendJsonPayload="true" enableJsonLayout="true">
      <layout xsi:type="JsonLayout" includeAllProperties="true">
        <attribute name="someProp" layout="prop" />
        <attribute name="nestedProp" encode="false">
          <layout type='JsonLayout'>
            <attribute name='insideNested1' layout='hello nested1!' />
            <attribute name='insideNested2' layout='hello nested2!' />
            <attribute name="nestedNestedProp" encode="false">
              <layout type='JsonLayout'>
                <attribute name='insideNestedNested1' layout='hello NestedNested1!' />
                <attribute name='insideNestedNested2' layout='hello NestedNested2!' />
              </layout>
            </attribute>
          </layout>
        </attribute>
      </layout>
    </target>
    <target name="console" xsi:type="Console" />
  </targets>

  <rules>
    <logger name="*" minlevel="Info" writeTo="stackdriver" />
    <logger name="*" minlevel="Info" writeTo="console" />
  </rules>
  
</nlog>