# Hybrid Runner environment variables reference

There are additional settings that can be configured through the use of these additional [`docker run`](https://docs.docker.com/engine/reference/commandline/run/) environment variables.

| Environment variable | Value                                                                                                                                                                                                                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BODY_LIMIT`         | Define the maximum request body size. The default value is `30mb`.                                                                                                                                                                                                                                                                                |
| `CUSTOM_API_ROUTE`   | <p>Define additional path location to the resources in hybrid runner.<br><br>Example: If this value is set to <code>mypath/torun</code> then the call to <code>v3/execute</code> would change from <code><http://localhost:3000/mytenant/api/v3/execute></code> to <code><http://localhost:3000/mypath/torun/mytenant/api/v3/execute></code>.</p> |
| `PORT`               | Set the service listening port. The default value is `3000`.                                                                                                                                                                                                                                                                                      |
| `UPLOAD_ENABLE`      | Allow Wasms to be uploaded to the Hybrid Runner directly using the `/upload` endpoint. This is not recommended to be used for production. The default value is `false`.                                                                                                                                                                           |

## Manage access to filesystem

By default, the runner requires read-write permissions to the following paths.

| Directory and path                                                                                                                                                                                                 | Description                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>Tenant resolver<br><code>/project/src/app/src/tenant\_resolver</code></p>                                                                                                                                       | <p>Purpose: Stores dynamically generated tenant-specific resolver JavaScript files.</p><p></p><p>Write pattern: Created once per tenant on the first request, rarely modified thereafter.</p><p></p><p>Example: <code>externalResolver\_\<tenant\_name>.js</code></p>                                            |
| <p>Service map cache<br><code>/project/src/app/src/services/servicemap</code></p><p></p><p>From <code>nodegen-server</code> <code>1.50.1</code> and onwards</p><p><code>/project/src/app/src/servicemap</code></p> | <p>Purpose: Caches service metadata (<code>servicemap.json</code>) to resolve models. This avoids repeated directory scanning.</p><p></p><p>Write pattern: Generated on application startup in offline mode. Recreated when model location changes.</p><p></p><p>Files created: <code>servicemap.json</code></p> |
| <p>Temporary file storage<br><code>/tmp</code></p>                                                                                                                                                                 | <p>Purpose: Store and caches Wasm. This is used by Node.js as the <code>tmp</code> library working directory.</p><p></p><p>Write pattern: Frequent writes during model downloads, cleaned up by graceful cleanup handlers.</p><p></p><p>Cleanup: Periodic cleanup of files older than <code>7</code> days.</p>   |

In [`nodegen-server`](https://github.com/orgs/Coherent-Partners/packages/container/package/nodegen-server) versions `>=1.50.2`, the locations of these paths can be customized using environment variables. If the account does not have read-write permissions to the locations above, this can be used to adjust the default paths.

| Environment variable               | Value                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <p><br><code>CACHE\_DIR</code></p> | <p>Cache write directory for Tenant resolver and Service map cache.</p><p></p><p>Default value are the paths noted above.</p><ul><li>To set an absolute path, start the path using <code>/</code>, e.g. <code>/var/runner\_cache</code>.</li><li>To set a relative path within the working directory, start the path using an eligible folder character, e.g. <code>runner\_cache</code> would be set to <code>./runner\_cache</code>.</li></ul> |
| `TEMP_DIR`                         | <p>Temporary file storage directory.</p><p></p><p>Default value is the path noted above.</p><ul><li>To set an absolute path, start the path using <code>/</code>, e.g. <code>/tmp</code>.</li><li>To set a relative path within the working directory, start the path using an eligible folder character, e.g. <code>tmp</code> would be set to <code>./tmp</code>.</li></ul>                                                                    |

## Control log output

In [`nodegen-server`](https://github.com/orgs/Coherent-Partners/packages/container/package/nodegen-server) versions `>=1.50.2`, more variables are available to manage log output.

| Environment variable    | Value                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOG_PATH`              | <p>Default: Logs are recorded to <code>stdout</code> only.</p><p></p><p>When defined, logs are saved to the defined location.</p><ul><li>To set an absolute path, start the path using <code>/</code>, e.g. <code>/var/runner\_logs</code>.</li><li>To set a relative path within the working directory, start the path using an eligible folder character, e.g. <code>runner\_logs</code> would be set to <code>./runner\_logs</code>.</li></ul> |
| `LOG_ROTATION_ENABLED`  | <p>Default: <code>true</code></p><p><br>This removes files that exceed the maximum log storage criteria.</p>                                                                                                                                                                                                                                                                                                                                      |
| `LOG_MAX_SIZE`          | <p>Default: <code>10M</code></p><p></p><p>Maximum file size before rotation:</p><ul><li><code>K</code> for kilobytes.</li><li><code>M</code> for megabytes.</li><li><code>G</code> for gigabytes.</li></ul>                                                                                                                                                                                                                                       |
| `LOG_ROTATION_INTERVAL` | <p>Default: <code>1d</code></p><p></p><p>Time-based rotation interval:</p><ul><li><code>h</code> for hours.</li><li><code>d</code> for days.</li><li><code>M</code> for months.</li></ul>                                                                                                                                                                                                                                                         |
| `LOG_MAX_FILES`         | <p>Default: <code>14</code></p><p></p><p>Maximum number of rotated log files to keep.</p>                                                                                                                                                                                                                                                                                                                                                         |
| `LOG_COMPRESSION`       | <p>Default: <code>false</code></p><p></p><p>Whether <code>gzip</code> compression is used on the log files.</p>                                                                                                                                                                                                                                                                                                                                   |

## Configure OpenTelemetry

Starting from [`nodegen-server`](https://github.com/orgs/Coherent-Partners/packages/container/package/nodegen-server) versions `>=1.46.0`, the image implements support for [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/). [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) is an observability framework and toolkit to facilitate the generation, export, collection of telemetry data. The package conducts auto-instrumentation using [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node). The data collected includes:

| Traces                                                                                                                                                                      | Metrics                                                                                                        | Attributes                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>HTTP request/response details</li><li>Route information</li><li>Request duration</li><li>Error details</li><li>Correlation IDs</li><li>Tenant information</li></ul> | <ul><li>Request counts</li><li>Error rates</li><li>Request duration</li><li>Memory usage (heap, RSS)</li></ul> | <ul><li>Service name and version</li><li>Environment</li><li>HTTP method and route</li><li>Status codes</li><li>Request IDs</li></ul> |

Below are links to documentation on integrating [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) with popular Application Performance Monitoring (APM) applications:

* Amazon CloudWatch: [OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html)
* Azure App Insights: [Application Insights with OpenTelemetry](https://learn.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview)
* Dynatrace: [OpenTelemetry & Dynatrace for intelligent observability](https://www.dynatrace.com/technologies/opentelemetry/) and  [OpenTelemetry and Dynatrace](https://docs.dynatrace.com/docs/ingest-from/opentelemetry)
* Elastic: [What is OpenTelemetry?](https://www.elastic.co/what-is/opentelemetry) and [Use OpenTelemetry with APM](https://www.elastic.co/docs/solutions/observability/apm/use-opentelemetry-with-apm)
* Sentry: [Code-level application monitoring for OpenTelemetry](https://sentry.io/for/opentelemetry/) and [OpenTelemetry Support](https://develop.sentry.dev/sdk/telemetry/traces/opentelemetry/)

The configuration of [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) in the hybrid runner is managed through environment variables defined in the Docker container. Information on the relevant environment variables can be found in:

* [SDK Configuration](https://opentelemetry.io/docs/languages/sdk-configuration/)
* [Environment Variable Specification](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/)

Key configuration variables include:

| Environment variable          | Value                                                                                                                                                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OTEL_SDK_DISABLED`           | Disable the SDK for all signals.                                                                                                                                                                                  |
| `OTEL_SERVICE_NAME`           | Sets the value of the `service.name` resource attribute.                                                                                                                                                          |
| `OTEL_RESOURCE_ATTRIBUTES`    | Key-value pairs to be used as resource attributes.                                                                                                                                                                |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | <p>If using the <a href="https://opentelemetry.io/docs/specs/otel/protocol/exporter/">OpenTelemetry Protocol Exporter</a>:</p><p>Target to which the exporter is going to send spans, metrics, or logs.</p>       |
| `OTEL_EXPORTER_OTLP_HEADERS`  | <p>If using the <a href="https://opentelemetry.io/docs/specs/otel/protocol/exporter/">OpenTelemetry Protocol Exporter</a>:</p><p>Key-value pairs to be used as headers associated with gRPC or HTTP requests.</p> |

## Manage compatible Neuron versions

{% hint style="info" %}
The compatibility feature in the runner is included in [`nodegen-server`](https://github.com/orgs/Coherent-Partners/packages/container/package/nodegen-server) `>=1.3.0`.

[Neuron](/build-spark-services/neuron.md) compiler versions `>=1.22.1` embed the compiler version into the ZIP package. If this feature is enabled and compiler version cannot be found, then the runner assume the [Neuron](/build-spark-services/neuron.md) version will be compatible.
{% endhint %}

The list of [Neuron](/build-spark-services/neuron.md) compatibility versions that can be found in the repository [`nodegen-server-compatibility`](https://github.com/Coherent-Partners/nodegen-server-compatibility).

[`nodegen-server`](https://github.com/orgs/Coherent-Partners/packages/container/package/nodegen-server) also has the ability to check whether [Neuron](/build-spark-services/neuron.md) Wasms are supported by the version of the runner you are using. This is done by downloading the JSON file from [`nodegen-server-compatibility`](https://github.com/Coherent-Partners/nodegen-server-compatibility) and assessing it against the versions of the runner and the requested Wasm. This can only be done with an online connection to fetch the necessary compatibility files.

This can be configured through the use of these additional [`docker run`](https://docs.docker.com/engine/reference/commandline/run/) environment variables.

| Environment variable                          | Value                                                                                                                                                                                                                                                                     |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NODEGEN_COMPATIBILITY_BASE_URL`              | <p>Base URL for Github user content.<br><br><code><https://raw.githubusercontent.com></code></p>                                                                                                                                                                          |
| `NODEGEN_COMPATIBILITY_PATH`                  | <p>Path to the JSON document in <a href="https://github.com/Coherent-Partners/nodegen-server-compatibility"><code>nodegen-server-compatibility</code></a>.<br><br><code>/Coherent-Partners/nodegen-server-compatibility/main/nodegen-server-compatibility.json</code></p> |
| `CHECK_RUNNER_COMPATIBILITY`                  | <p><code>true</code> or <code>false</code></p><p></p><p>Whether to check if the version of the runner supports this version of <a data-mention href="/pages/qc2ynJ5gnthNAqVrFQRg">/pages/qc2ynJ5gnthNAqVrFQRg</a>. The default value is <code>false</code>.</p>           |
| `EXECUTE_WITH_WARNING`                        | <p><code>true</code> or <code>false</code> </p><p><br>If <code>CHECK\_RUNNER\_COMPATIBILITY</code> is <code>true</code>, this defines whether or not to continue with executing the Spark service but with a warning. The default value is <code>false</code>.</p>        |
| `NODEGEN_COMPATIBILITY_LIST_REFRESH_INTERVAL` | If `CHECK_RUNNER_COMPATIBILITY` is `true`, this defines how often in minutes to fetch the  [`nodegen-server-compatibility`](https://github.com/Coherent-Partners/nodegen-server-compatibility) JSON document. The default value is `1440`.                                |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coherent.global/hybrid-runner/setup-the-hybrid-runner/hybrid-runner-environment-variables-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.