Table of Contents
Last updated: 6/17/2026

OpenTelemetry Collector installation

The ShareAspace OpenTelemetry Collector is an optional component used to collect OpenTelemetry signals (logs, metrics, and traces) and export them to file storage.

It is intended for simple deployments where no external observability platform (e.g. OpenTelemetry backend or Azure Monitor) is used.

The OpenTelemetry Collector is not required if telemetry is sent to an external OpenTelemetry-compatible system or Azure Monitor.

Prerequisites

The OpenTelemetry Collector requires:

  • See Software prerequisites.
  • A TLS certificate configured for the collector endpoint.
  • A configured ShareAspace Host and extensions that will send telemetry data.
Note

The ShareAspace OpenTelemetry Collector does not rely on IIS. It runs using an embedded web server and requires no IIS configuration.

Installation steps

Step 1: Run the installer

Run the OpenTelemetryCollector.msi installer to install the ShareAspace OpenTelemetry Collector.

The service will be installed as a Windows Service named ShareAspace OpenTelemetry Collector.

Step 2: Configure the collector

See the Configuration section.

Step 3: Start the service

Ensure the service startup type is configured appropriately (e.g. Automatic), then start the ShareAspace OpenTelemetry Collector service.

Step 4: Verify installation

Verify that the collector is running and that telemetry data is written to the configured log directory.

Log output

When the collector is configured with a base path such as F:\Logging and receives signals from a service (e.g. ShareAspace.SampleService), the following files are 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 using JSON Lines.

Authentication options

Two authentication methods are supported:

API-key authentication

The collector is configured with one or more API keys. Clients must include the x-otlp-api-key header in their requests.

Clients authenticate using X.509 certificates (mutual TLS). The collector maintains a whitelist of allowed certificate thumbprints.

Configuration

Open the appsettings.json file located in the ShareAspace OpenTelemetry Collector installation folder.

By default: C:\Program Files\Eurostep\ShareAspace\OTelCollector\appsettings.json

Common configuration considerations

Warning

Only HTTPS endpoints are supported. HTTP is not supported.

The collector supports both:

  • gRPC (recommended)
  • HTTP/Protobuf

If required, HTTP/Protobuf may be used instead of gRPC:

  • Use HttpEndpointUrl instead of GrpcEndpointUrl.
  • Configure OtlpHttp instead of OtlpGrpc.
  • Typical ports:
    • 4317 for gRPC.
    • 4318 for HTTP/Protobuf.

Configuration: API-key authentication

Configure the collector to use API-key authentication:

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

Up to two API keys may be configured using PrimaryApiKey and SecondaryApiKey.

For improved security, these values can be provided through environment variables:

  • ShareAspace__OpenTelemetry__PrimaryApiKey
  • ShareAspace__OpenTelemetry__SecondaryApiKey

After configuration, ensure clients (Host and extensions) are configured accordingly as described in OpenTelemetry Logging.

Configuration: certificate authentication

Configure the collector to use client certificate authentication (mutual TLS).

First, generate client certificates and collect their thumbprints.

Warning

The collector validates certificates using a thumbprint whitelist. Adding certificates to the system trust store alone is not sufficient.

Example configuration:

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

Only subject-based certificate lookup is supported. Ensure that exactly one certificate matches the configured subject.

After configuration, ensure clients are configured accordingly as described in OpenTelemetry Logging.

Configuration property descriptions

  • MaxLogFileSize – Maximum log file size (in mebibytes) before rotation.
  • Thumbprint – X.509 certificate thumbprint (SHA1 or SHA256 supported).
  • Location, Store, Subject – Certificate location parameters corresponding to the Windows certificate store.