Table of Contents
Last updated: 12/12/2025

OpenTelemetry collector

ShareAspace offers a single-MSI OpenTelemetry collector that logs OpenTelemetry signals into text files. It allows a simple system setup if your infrastructure does not rely on OpenTelemetry for observability.

There is no need to install ShareAspace OpenTelemetry collector if you will be configuring OpenTelemetry logging to an OpenTelemetry-compatible system or to Azure Monitor.

Log output

When the collector is configured with the base path F:\Logging and receives logs and other signals from a service named ShareAspace.SampleService, the following files will be created:

  • F:\Logging\ShareAspace.SampleService\Logs\YYYY-MM-DD_####.jsonl
  • F:\Logging\ShareAspace.SampleService\Metrics\YYYY-MM-DD_####.jsonl
  • F:\Logging\ShareAspace.SampleService\Traces\YYYY-MM-DD_####.jsonl

These files contain logs, metrics, and traces (collectively referred to as signals) in the OpenTelemetry Protocol File format based on JSON Lines.

Prerequisites

Run installer OpenTelemetryCollector.msi to install the ShareAspace OpenTelemetry collector. It will be installed as a Windows Service named "ShareAspace OpenTelemetry collector".

Note

The service is not set to start automatically by default. Ensure an appropriate startup mode is set after configuring the collector.

A server certificate with extendedKeyUsage = critical, serverAuth shall be provisioned and installed into the certificate store. The service account running the "ShareAspace OpenTelemetry collector" service must have access to the certificate and the associated private key. This is necessary in both cases - whether you configure the collector to use API-key authentication or certificate authentication. If the collector is installed on the same node as the Service Host, the internal certificate for the host may be reused to configure the collector.

Note

The ShareAspace OpenTelemetry collector does not rely on IIS. Instead, it runs an embedded web server. The setup does not involve any IIS configuration steps.

Afterwards, the authentication needs to be set up for the collector. Two exclusive options are available:

  1. API-key authentication. The server is set up with a cryptographically random secret that is distributed to the extensions. The clients need to send a correct x-otlp-api-key header for the signals to be accepted.
  2. Certificate authentication (recommended). Each extension needs to generate a client X.509 certificate (i.e., with a clientAuth extended key usage). The collector maintains a whitelist of client certificate thumbprints that are allowed to connect and send OpenTelemetry signals. With the server presenting a server TLS certificate to each client, this sets up a mutual TLS authentication. This option works best if a private certificate authority (private CA, private PKI) is already used in the target deployment infrastructure (e.g., using Azure Certificate Authority or Kubernetes cert-manager).

Common configuration considerations

Warning

ShareAspace OpenTelemetry clients and the ShareAspace OpenTelemetry collector only support HTTPS endpoint. Attempts to use plain HTTP may fail.

While the collector supports both gRPC (recommended) and HTTP/Protobuf protocols (simultaneously, if needed), there is no need to configure both if all the extensions are configured to use the same protocol when sending the OpenTelemetry signals. If you are experiencing any issues with the gRPC protocol, e.g. due to your networking infrastructure, the OpenTelemetry Collector may be configured to use a plain HTTP/protobuf protocol. Make the following changes:

  • Set HttpEndpointUrl instead of GrpcEndpointUrl (it is recommended to use port 4317 for gRPC, and 4318 for HTTP/Protobuf)
  • Configure OtlpHttp instead of OtlpGrpc (same configuration parameter set)

Configuration for API-key authentication (Alternative 1)

Follow this section if you decided to run ShareAspace OpenTelemetry collector with authentication based on API keys. Client certificates are not used in this setup.

Edit the appsettings.json for the ShareAspace OpenTelemetry collector (normally located at C:\Program Files\Eurostep\ShareAspace\OTelCollector) as follows:

{
  "Logging": {
    // ...
  },
  // ...
  "ShareAspace": {
    "OpenTelemetry": {
      "AuthMode": "ApiKey",
      "PrimaryApiKey": "REDACTED",
      "SecondaryApiKey": "REDACTED",
      "GrpcEndpointUrl": "https://__SHAREASPACE_COLLECTOR_HOSTNAME__:4317",
      "Exports": {
        "File": {
          "BasePath": "F:\\Logging\\Path",
          "MaxLogFileSize": 300
        }
      }
    }
  },
  "Kestrel": {
    "Endpoints": {
      "OtlpGrpc": {
        "Url": "https://__SHAREASPACE_COLLECTOR_HOSTNAME__:4317",
        "Certificate": {
          "Store": "My",
          "Location": "LocalMachine",
          "Subject": "__SHAREASPACE_LOCAL_HOSTNAME_CERT__",
          "AllowInvalid": false
        },
      }
    }
  }
}

Up to two keys may be configured using PrimaryApiKey and SecondaryApiKey. For security reasons, the collector service may be started with the following environment variables set instead of writing those keys on disk: ShareAspace__OpenTelemetry__PrimaryApiKey and ShareAspace__OpenTelemetry__SecondaryApiKey.

After configuring the ShareAspace OpenTelemetry collector with key-based authentication, proceed with client configuration (ShareAspace Service Host and extensions) as described above under OpenTelemetry with API-key authentication in the OpenTelemetry Logging.

Configuration for certificate authentication (Alternative 2)

Follow this section if you decided to run ShareAspace OpenTelemetry collector with authentication based on client certificates for mutual TLS authentication. No API keys are used in this setup.

First, follow the TLS certificates guide to generate as many client certificates as there are extensions that you would like to whitelist for streaming OpenTelemetry signals. Make sure to also obtain a thumbprint for every generated certificate (SHA256 thumbprints are recommended) and note them down for the subsequent setup.

Warning

The certificate validation is performed using a thumbprint whitelist independent of the certificate trust on the host system. Adding certificates to the system trust is not sufficient for the ShareAspace OpenTelemetry Collector to accept signals from client configured to use the said certificates.

Edit the appsettings.json for the ShareAspace OpenTelemetry collector (normally located at C:\Program Files\Eurostep\ShareAspace\OTelCollector) as follows:

{
  "Logging": {
    // ...
  },
  // ...
  "ShareAspace": {
    "OpenTelemetry": {
      "AuthMode": "ClientCertificate",
      "AllowedCertificates": [
        {
          "Thumbprint": "bc72a2042393c3e341352e489ef5e0af934b80d0"
        },
        {
          "Thumbprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        }
      ],
      "GrpcEndpointUrl": "https://__SHAREASPACE_COLLECTOR_HOSTNAME__:4317",
      "Exports": {
        "File": {
          "BasePath": "F:\\Logging\\Path",
          "MaxLogFileSize": 300
        }
      }
    }
  },
  "Kestrel": {
    "Endpoints": {
      "OtlpGrpc": {
        "Url": "https://__SHAREASPACE_COLLECTOR_HOSTNAME__:4317",
        "ClientCertificateMode": "RequireCertificate",
        "Certificate": {
          "Store": "My",
          "Location": "LocalMachine",
          "Subject": "__SHAREASPACE_LOCAL_HOSTNAME_CERT__",
          "AllowInvalid": false
        },
      }
    }
  }
}
Warning

ShareAspace OpenTelemetry Collector only supports a subject-based certificate lookup. The lookup will only work if there exactly one certificate with the specified subject within a given store.

After configuring the ShareAspace OpenTelemetry collector with key-based authentication, proceed with client configuration (ShareAspace Service Host and extensions) as described above under OpenTelemetry with certificate authentication in the OpenTelemetry Logging.

Configuration property descriptions

  • MaxLogFileSize - maximum log size in mebibytes until log file rotation.
  • Thumbprint - X.509 certificate thumbprint (standard SHA1-based thumbprints as reported by Windows as well as SHA256-based ones are accepted).
  • Location, Store, and Subject - for a certificate location cert:\LocalMachine\My\certSubject, Location=LocalMachine, Store=My, Subject=certSubject.