Troubleshooting Common APM Issues

This section covers frequently encountered problems during Middleware APM setup and provides simple explanations and verified solutions.

1. Connection Errors: “StatusCode.UNAVAILABLE” During Data Export

Error Example:

1WARNING:opentelemetry.exporter.otlp.proto.grpc.exporter:Transient error StatusCode.UNAVAILABLE encountered while exporting logs to localhost:9319, retrying in 8s.
2WARNING:opentelemetry.exporter.otlp.proto.grpc.exporter:Transient error StatusCode.UNAVAILABLE encountered while exporting logs to localhost:9319, retrying in 16s.

Why it Happens:

This usually occurs when the APM setup tries to export telemetry data to localhost:9319, but there’s no local Middleware agent running.

In other words, the SDK is configured for a host-based setup (where the agent runs locally), but no host agent is actually installed. Alternatively, the APM is not configured to send data directly to Middleware servers in a serverless setup.

Solution:

Make sure you are using the correct setup type:

• If using host-based, install and run the Middleware Agent.
• If using serverless, configure your APM SDK to send data directly to Middleware servers instead of localhost.

2. NPM Installation Fails on Windows

Error Example (PowerShell):

1npm install @middleware.io/node-apm

This triggers:

The splatting operator '@' cannot be used to reference variables in an expression. '@middleware' can be used only as an argument to a command.

Why it Happens:

This issue is specific to Windows environments, particularly when using PowerShell. In PowerShell, the @ symbol is interpreted as a variable or “splatting” operator. Due to this, @middleware isn’t recognized as part of the package name.

Solution:

Wrap the package name in quotes when installing via npm:

1npm i "@middleware.io/node-apm"

This ensures the package name is correctly interpreted by PowerShell.

3. Version Conflicts with OpenTelemetry Packages (Python)

Error Example:

1ContextualVersionConflict
2pkg_resources.ContextualVersionConflict: (opentelemetry-instrumentation-wsgi 0.52b0, Requirement.parse('opentelemetry-instrumentation-wsgi==0.48b0'), {'opentelemetry-instrumentation-flask', ...})

Why it Happens:

This occurs when multiple versions of OpenTelemetry SDKs or instrumentation libraries are installed on the same machine or environment. Middleware APM depends on specific versions of OpenTelemetry components, and conflicts arise if other OTEL SDKs are already installed globally or within the same virtual environment.

Solution:

Ensure a clean environment before installing Middleware APM:

• Remove any existing OpenTelemetry-based SDKs.
• Or, install Middleware APM in an isolated virtual environment separate from other OTEL libraries.