> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/hybrid-runner/how-to-set-up-the-hybrid-runner/hybrid-runner-reference.md).

# Hybrid runner reference

There are additional settings that can be configured through the use of these additional [`docker container 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>Write pattern: Created once per tenant on the first request, rarely modified thereafter.</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>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>Write pattern: Generated on application startup in offline mode. Recreated when model location changes.</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>Write pattern: Frequent writes during model downloads, cleaned up by graceful cleanup handlers.</p><p>Cleanup: Periodic cleanup of files older than <code>7</code> days.</p>   |

In `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>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>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` 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>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>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>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>Maximum number of rotated log files to keep.</p>                                                                                                                                                                                                                                                                                                                                                         |
| `LOG_COMPRESSION`       | <p>Default: <code>false</code></p><p>Whether <code>gzip</code> compression is used on the log files.</p>                                                                                                                                                                                                                                                                                                                                   |

## Configure OpenTelemetry

Starting from `nodegen-server` versions `>=1.46.0`, the image implements support for [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/). 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 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 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> |