update to version 3.6.0, cleanup docs and comments

Author: manigandham

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Readme: https://github.com/manigandham/serilog-sinks-googlecloudlogging/blob/master/README.md
 
+## 3.6.0
+- Add `TraceSampled` to log correlation set of properties.
+- Update documentation.
+
 ## 3.5.0
 - Refactored sink to accept [`ITextFormatter`](https://github.com/serilog/serilog/wiki/Formatting-Output#custom-text-formatters) for full control over rendering a log event.
 - Config validation on sink initialization will throw exceptions for known bad config values.

README.md

@@ -6,7 +6,7 @@ Built for `netstandard2.0`, `net5.0`
 
 Release notes here: [CHANGELOG.md](CHANGELOG.md)
 
-## Getting started
+## Usage
 
 #### Install [package from Nuget](https://www.nuget.org/packages/Serilog.Sinks.GoogleCloudLogging/):
 
@@ -23,9 +23,10 @@ Log.Logger = new LoggerConfiguration().WriteTo.GoogleCloudLogging(config).Create
 
 #### Configure Logger (using config file):
 
-This requires ['serilog-settings-configuration'](https://github.com/serilog/serilog-settings-configuration) to load sinks using an `appsettings.json` file.
+This requires the [`serilog-settings-configuration`](https://github.com/serilog/serilog-settings-configuration) package.
 
 ```json
+// appsettings.json or other config file
 "Serilog": {
  "Using": [ "Serilog.Sinks.GoogleCloudLogging" ],
  "MinimumLevel": "Information",
@@ -52,32 +53,33 @@ var config = new ConfigurationBuilder().AddJsonFile("appsettings.json", optional
 Log.Logger = new LoggerConfiguration().ReadFrom.Configuration(config).CreateLogger();
 ```
 
-#### GCP authentication:
+## GCP Authentication:
 
-This library uses the [`Google-Cloud-Dotnet`](https://googleapis.github.io/google-cloud-dotnet/) libraries which authenticate using the [Application Default Credentials](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application) found on the host. This is automatic on GCE VMs or you can use the [`gcloud`](https://cloud.google.com/sdk/) SDK to authenticate manually. The service account must have the [`Logs Writer`](https://cloud.google.com/logging/docs/access-control) permission to send logs.
+This library uses the [Google Cloud .NET](https://cloud.google.com/dotnet/docs) client libraries which authenticate using the [Application Default Credentials](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application) found on the host. This is automatic on Google Cloud (GCE, GKE, Cloud Run, AppEngine) or you can use the [gcloud SDK](https://cloud.google.com/sdk/) to authenticate manually. 
+
+The service account requires the [`Logs Writer`](https://cloud.google.com/logging/docs/access-control) permission to send logs.
 
 ## Sink Options
 
 Name | Default | Description
 ---- | ------- | -----------
 `ProjectId` | | Google Cloud project ID where logs will be sent. Will be automatically set to host project if running in GCP, otherwise required.
-`ResourceType` | `global` | Resource type for all log output. Will be automatically discovered if running in GCP, otherwise required. Must be one of the supported types listed in the [cloud logging documentation](https://cloud.google.com/logging/docs/api/v2/resource-list).
-`LogName` | `Default` | Name of the log. This is required if `UseSourceContextAsLogName` is false.
+`ResourceType` | `"global"` | Resource type for all log output. Will be automatically discovered if running in GCP, otherwise required. See [Monitored Resources and Services](https://cloud.google.com/logging/docs/api/v2/resource-list) for supported types.
+`LogName` | `"Default"` | Name of the log.
 `Labels` | | `Dictionary<string, string>` of properties added to all log entries.
 `ResourceLabels` | | `Dictionary<string, string>` of properties added to all log entries, at the resource level. See [Monitored Resources and Services](https://cloud.google.com/logging/docs/api/v2/resource-list) for recognized labels.
-`UseSourceContextAsLogName` | True | The log name for a log entry will be set to the [SourceContext](https://github.com/serilog/serilog/wiki/Writing-Log-Events#source-contexts) property if it's available.
-`UseJsonOutput` | False | Structured logs can be sent as text with labels or as a JSON object, see details below.
-`GoogleCredentialJson` | | GCP client libraries use [Application Default Credentials](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application). If these are not available or you need to use other credentials, set the JSON text of a credential file directly.
+`UseSourceContextAsLogName` | True | The log name for a log entry will be set to the [SourceContext](https://github.com/serilog/serilog/wiki/Writing-Log-Events#source-contexts) property if available.
+`UseJsonOutput` | False | Serialize log entries as JSON for structured logging. See details below.
+`UseLogCorrelation` | False | Integrate logs with [Cloud Trace](https://cloud.google.com/trace) by setting `Trace`, `SpanId`, `TraceSampled` properties if available.
 `ServiceName` | | Name of the service added as metadata to log entries. Required to forward logged exceptions to Google Cloud Error Reporting. Must also set `UseJsonOutput` to true.
 `ServiceVersion` | | Version of the service added as metadata to log entries.
+`GoogleCredentialJson` | | GCP client libraries use [Application Default Credentials](https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application). If these are not available or you need to use other credentials, set the content of a JSON credential file directly.
 
-#### Output Type
-
-Serilog uses structured logging which means each log line is a formatting template with attached properties that are combined to create the final output. When `UseJsonOutput` is false, the output is sent as `TextPayload` to GCP with any properties serialized to string key/value labels.
+## Logging Output
 
-If `UseJsonOutput` is set to true, the output will be sent as `JsonPayload` to maintain the original data types. This is helpful for querying child properties or numeric values in the Log Viewer, and will also capture property names even if they have null values.
+Serilog uses structured logging but logs are sent to GCP as a `TextPayload` with properties serialized to string labels by default. Enable `UseJsonOutput` to send logs as a `JsonPayload` with the proper data types. This provides richer logs with better querying support and will also capture property names even if they have null values.
 
-WARNING: JSON output only accepts numeric values as `double` so all numbers will be converted. Large integers and floating-point values will lose precision. If you want the exact value preserved then log it as a string instead.
+*NOTE*: JSON output only accepts numeric values as `double` so all numbers will be converted. Large integers and floating-point values will lose precision. If you want the exact value preserved then log it as a string instead.
 
 #### Log Level Mapping
 
@@ -92,6 +94,6 @@ Warning | Warning
 Error | Error
 Fatal | Critical
 
-## Viewing Logs
+#### Viewing Logs
 
-Logs will appear in the Google Cloud Console Log Viewer: https://console.cloud.google.com/logs/viewer
+View and query logs in the Google Cloud Console Logs Explorer: https://console.cloud.google.com/logs/viewer

src/Serilog.Sinks.GoogleCloudLogging/GoogleCloudLoggingSinkOptions.cs

@@ -39,13 +39,13 @@ public class GoogleCloudLoggingSinkOptions
  public bool UseSourceContextAsLogName { get; set; }
 
  /// <summary>
- /// Serialize log entries as JSON object instead of strings to preserve structure and data types for rich querying.
+ /// Serialize log entries as JSON objects instead of strings to preserve structure and data types for rich querying.
  /// Disabled by default. Must be enabled for logged exceptions to be forwarded to StackDriver Error Reporting.
  /// </summary>
  public bool UseJsonOutput { get; set; }
 
  /// <summary>
- /// Integrate logs with Cloud Trace by setting LogEntry.Trace and LogEntry.SpanId if the LogEvent contains TraceId and SpanId properties.
+ /// Integrate logs with Cloud Trace by setting `Trace`, `SpanId`, `TraceSampled` properties on the LogEvent.
  /// Required for Google Cloud Trace Log Correlation.
  /// See https://cloud.google.com/trace/docs/trace-log-integration
  /// </summary>

src/Serilog.Sinks.GoogleCloudLogging/LogFormatter.cs

@@ -119,7 +119,7 @@ public void WritePropertyAsLabel(LogEntry log, string propKey, LogEventPropertyV
  break;
 
  case SequenceValue sequenceValue:
- log.Labels.Add(propKey, string.Join(",", sequenceValue.Elements));
+ log.Labels.Add(propKey, String.Join(",", sequenceValue.Elements));
  break;
 
  case StructureValue structureValue when structureValue.Properties.Count > 0:

src/Serilog.Sinks.GoogleCloudLogging/Serilog.Sinks.GoogleCloudLogging.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
  <PropertyGroup>
- <PackageVersion>3.5.0</PackageVersion>
+ <PackageVersion>3.6.0</PackageVersion>
  <Description>Serilog sink that writes events to Google Cloud Platform (Stackdriver) Logging.</Description>
  <Authors>Mani Gandham</Authors>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>