Set-NCacheOpenTelemetry

The Set-NCacheOpenTelemetry PowerShell cmdlet configures OpenTelemetry settings for an NCache server. It allows users to configure metrics and logs endpoints and their respective protocols. The endpoints must be specified using an IP address followed by a port number. Metrics and logs can be configured independently.

The cmdlet also allows users to enable client-side telemetry. When client telemetry is enabled, clients export metrics to the cache server's advertised IP address using the configured metrics port. Ensure that an OTLP receiver is accessible at this address and port. No separate OpenTelemetry configuration is required on the client machines.

Note

To publish client metrics, the OpenTelemetry Collector must run on the cache server because clients use the cache server's IP address and configured metrics port. A remote Collector can receive server-side metrics but does not receive client metrics directly.

Set-NCacheOpenTelemetry [-MetricsEndpoint] [-LogsEndpoint] `
                        [-MetricsProtocol] [-LogsProtocol] `
                        [-Server] [-Enabled] `
                        [-ClientEnabled] [-NoLogo] `
                        [-Credentials] [-TlsCertPath]`
                        [-TlsCertPassword]

Examples

  • This command enables OpenTelemetry and configures metrics and logs to be exported to the specified OpenTelemetry endpoint using gRPC.

    Set-NCacheOpenTelemetry -MetricsEndpoint 20.200.20.12:4317 -LogsEndpoint 20.200.20.12:4317 `
                        -LogsProtocol Grpc -MetricsProtocol Grpc `
                        -Enabled True

  • This command enables OpenTelemetry on the specified NCache server and configures metrics and logs to be exported to the specified endpoint using HTTP.

    Set-NCacheOpenTelemetry -MetricsEndpoint 20.200.20.12:4318 -MetricsProtocol Http `
                        -LogsEndpoint 20.200.20.12:4318 -LogsProtocol Http `
                        -Server 20.200.20.11 -Enabled True

  • This command enables OpenTelemetry metrics on the server and also enables metrics publishing from connected clients. Clients receive the cache server's advertised IP address and configured metrics port when they connect.

    Set-NCacheOpenTelemetry -MetricsEndpoint 20.200.20.56:4317 -MetricsProtocol Grpc `
                        -ClientEnabled -Enabled True

  • This command disables server-side OpenTelemetry on the local NCache server. 

    Set-NCacheOpenTelemetry -Enabled False

  • This command enables OpenTelemetry on the specified NCache server and configures metrics and logs to be exported using HTTP. It also provides a client certificate and password for the secure management connection.

    Set-NCacheOpenTelemetry -MetricsEndpoint 20.200.20.12:4318 -MetricsProtocol Http `
                        -LogsEndpoint 20.200.20.12:4318 -LogsProtocol Http `
                        -Server 20.200.20.11 -Enabled True `
                        -TlsCertPath "C:\certs\client.pem" `
                        -TlsCertPassword "clientKeyPassword"
Important

To export OpenTelemetry metrics and logs over HTTPS, configure the OpenTelemetry Collector with a TLS certificate and private key (e.g., C:\OpenTelemetry\certs\). Specify their paths in the Collector configuration and ensure the NCache server trusts the certificate.

  • This command enables OpenTelemetry on NCache server 20.200.20.11 and configures metrics and logs to be exported to the OpenTelemetry Collector at 20.200.20.12:4318 using HTTPS.
Set-NCacheOpenTelemetry -Server 20.200.20.11 -MetricsEndpoint 20.200.20.12:4318 `
                        -MetricsProtocol Https -LogsEndpoint 20.200.20.12:4318 `
                        -LogsProtocol Https -Enabled True

Properties

Note

The -MetricsProtocol and -LogsProtocol parameters are optional. If not specified, the corresponding protocol defaults to Http. When enabling OpenTelemetry, at least one metrics or logs endpoint must be specified.

Note

The Set-NCacheOpenTelemetry cmdlet replaces the existing OpenTelemetry configuration. Parameters omitted from a command do not retain their previously configured values. To preserve existing settings, specify all required endpoints, protocols, and enablement options each time you run the cmdlet.

Parameters Data Types Description Default Value
-MetricsEndpoint <String> Specifies the endpoint where OpenTelemetry metrics are exported. The endpoint can be specified using an IP address followed by a port number. -
-LogsEndpoint <String> Specifies the endpoint where OpenTelemetry logs are exported. The endpoint must be specified using an IP address followed by a port number. -
-MetricsProtocol <OpenTelemetryProtocol> Specifies the protocol used to export metrics. Supported values are Http, Https, and Grpc. The default is Http. Http
-LogsProtocol <OpenTelemetryProtocol> Specifies the protocol used to export logs. Supported values are Http, Https, and Grpc. The default is Http. Http
-Server <String> Specifies one or more cache-server hostnames or IP addresses on which OpenTelemetry configuration is to be updated. -
-Enabled <Boolean> Enables or disables OpenTelemetry on the specified NCache server. Set this parameter to True to enable OpenTelemetry or False to disable it. False
-ClientEnabled <SwitchParameter> Publishes metrics from the clients connected to the specified server as well as from the server itself. Clients receive the metrics endpoint from the server when they connect. If this switch is not specified, client telemetry is disabled. False
-NoLogo <SwitchParameter> Suppresses display of the logo banner. False
-TlsCertPath <String> Path to the client PEM certificate used to authenticate the machine running the NCache PowerShell cmdlet when connecting to an NCache server with mutual TLS (mTLS) enabled. The PEM file must contain the private key, leaf certificate, and any intermediate certificates. You can generate a certificate using New-NCacheTlsCertificate. -
-TlsCertPassword <String> Password used to load the encrypted private key in the PEM file specified by -TlsCertPath. Required only when the private key is password-protected. Not needed for an unencrypted private key. -
Note

OpenTelemetry configuration changes do not automatically reinitialize existing exporters. Restart all relevant NCache processes for the updated settings to take effect.