Skip to content

docs: document DENO_AUDIT_PERMISSIONS=otel #3090

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lunadogbot wants to merge 3 commits into
base: 2.8
Choose a base branch
from
Open

docs: document DENO_AUDIT_PERMISSIONS=otel #3090

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
87ce3cb
docs: document `DENO_AUDIT_PERMISSIONS=otel` (2.8)
lunadogbot Apr 29, 2026
6f9ae51
docs: drop 2.8-specific framing for DENO_AUDIT_PERMISSIONS=otel
lunadogbot May 2, 2026
fa1006e
docs: deno fmt
lunadogbot May 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 23 additions & 5 deletions runtime/fundamentals/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,10 +96,11 @@ By default, Deno will not generate a stack trace for permission requests as it
comes with a hit to performance. Users can enable stack traces with the
`DENO_TRACE_PERMISSIONS` environment variable to `1`.

Deno can also generate an audit log of all accessed permissions; this can be
achieved using the `DENO_AUDIT_PERMISSIONS` environment variable to a path. This
works regardless if permissions are allowed or not. The output is in JSONL
format, where each line is an object with the following keys:
Deno can also generate an audit log of all accessed permissions, regardless of
whether the access was allowed or denied.

Set `DENO_AUDIT_PERMISSIONS` to a **file path** to write JSONL — each line is an
object with the following keys:

- `v`: the version of the format
- `datetime`: when the permission was accessed, in RFC 3339 format
Expand All @@ -112,7 +113,24 @@ A schema for this can be found in

In addition, this env var can be combined with the above-mentioned
`DENO_TRACE_PERMISSIONS`, which then adds a new `stack` field to the entries
which is an array contain all the stack trace frames.
which is an array containing all the stack trace frames.

You can also set `DENO_AUDIT_PERMISSIONS=otel` to emit each access as an
OpenTelemetry **log record** instead of writing to a file. The records are sent
to whichever exporter you have configured via
[`OTEL_DENO`](/runtime/fundamentals/open_telemetry/) and carry these attributes:

- `deno.permission.type`
- `deno.permission.value`
- `deno.permission.stack` (if `DENO_TRACE_PERMISSIONS` is also set)

This is the recommended setup if you already collect OpenTelemetry data — the
permission audit lands next to your traces and metrics so you can correlate it
with request handling.

```sh
OTEL_DENO=true DENO_AUDIT_PERMISSIONS=otel deno run -A main.ts
```

### Configuration file

Expand Down
45 changes: 23 additions & 22 deletions runtime/reference/env_variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,25 +138,26 @@ examples.

The Deno runtime has these special environment variables.

| name | description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DENO_AUTH_TOKENS | A semi-colon separated list of bearer tokens and hostnames to use when fetching remote modules from private repositories<br />(e.g. `abcde12345@deno.land;54321edcba@github.com`) |
| DENO_TLS_CA_STORE | Comma-separated list of order dependent certificate stores.<br />Possible values: `system`, `mozilla`. Defaults to `mozilla`. |
| DENO_CERT | Load certificate authority from PEM encoded file |
| DENO_COVERAGE_DIR | Set the directory for collecting coverage profile data. This option only works for [`deno test` subcommand](/runtime/reference/cli/test/). |
| DENO_DIR | Set the cache directory |
| DENO_INSTALL_ROOT | Set deno install's output directory (defaults to `$HOME/.deno/bin`) |
| DENO_REPL_HISTORY | Set REPL history file path History file is disabled when the value is empty <br />(defaults to `$DENO_DIR/deno_history.txt`) |
| DENO_NO_PACKAGE_JSON | Disables auto-resolution of `package.json` |
| DENO_NO_PROMPT | Set to disable permission prompts on access<br />(alternative to passing `--no-prompt` on invocation) |
| DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available |
| DENO_V8_FLAGS | Set V8 command line options |
| DENO_JOBS | Number of parallel workers used for the `--parallel` flag with the test subcommand.<br />Defaults to number of available CPUs. |
| DENO_KV_ACCESS_TOKEN | Personal access token used when connecting to Deno KV databases (for example via [`Deno.openKv`](/api/deno/~/Deno.openKv) or `@deno/kv` with a KV Connect URL). |
| DENO_WEBGPU_TRACE | Path to a directory to output a [WGPU trace](https://github.com/gfx-rs/wgpu/pull/619) to when using the WebGPU API |
| DENO_WEBGPU_BACKEND | Select the backend WebGPU will use, or a comma separated list of backends in order of preference. Possible values are `vulkan`, `dx12`, `metal`, or `opengl` |
| HTTP_PROXY | Proxy address for HTTP requests (module downloads, fetch) |
| HTTPS_PROXY | Proxy address for HTTPS requests (module downloads, fetch) |
| NPM_CONFIG_REGISTRY | URL to use for the npm registry. |
| NO_COLOR | Set to disable color |
| NO_PROXY | Comma-separated list of hosts which do not use a proxy (module downloads, fetch) |
| name | description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DENO_AUTH_TOKENS | A semi-colon separated list of bearer tokens and hostnames to use when fetching remote modules from private repositories<br />(e.g. `abcde12345@deno.land;54321edcba@github.com`) |
| DENO_TLS_CA_STORE | Comma-separated list of order dependent certificate stores.<br />Possible values: `system`, `mozilla`. Defaults to `mozilla`. |
| DENO_CERT | Load certificate authority from PEM encoded file |
| DENO_COVERAGE_DIR | Set the directory for collecting coverage profile data. This option only works for [`deno test` subcommand](/runtime/reference/cli/test/). |
| DENO_DIR | Set the cache directory |
| DENO_INSTALL_ROOT | Set deno install's output directory (defaults to `$HOME/.deno/bin`) |
| DENO_REPL_HISTORY | Set REPL history file path History file is disabled when the value is empty <br />(defaults to `$DENO_DIR/deno_history.txt`) |
| DENO_NO_PACKAGE_JSON | Disables auto-resolution of `package.json` |
| DENO_NO_PROMPT | Set to disable permission prompts on access<br />(alternative to passing `--no-prompt` on invocation) |
| DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available |
| DENO_V8_FLAGS | Set V8 command line options |
| DENO_JOBS | Number of parallel workers used for the `--parallel` flag with the test subcommand.<br />Defaults to number of available CPUs. |
| DENO_KV_ACCESS_TOKEN | Personal access token used when connecting to Deno KV databases (for example via [`Deno.openKv`](/api/deno/~/Deno.openKv) or `@deno/kv` with a KV Connect URL). |
| DENO_AUDIT_PERMISSIONS | Audit every permission access. Set to a file path to write JSONL, or to the literal value `otel` to emit OpenTelemetry log records via the configured OTel exporter. See [permissions audit](/runtime/fundamentals/security/#permission-flags) for the field set. |
| DENO_WEBGPU_TRACE | Path to a directory to output a [WGPU trace](https://github.com/gfx-rs/wgpu/pull/619) to when using the WebGPU API |
| DENO_WEBGPU_BACKEND | Select the backend WebGPU will use, or a comma separated list of backends in order of preference. Possible values are `vulkan`, `dx12`, `metal`, or `opengl` |
| HTTP_PROXY | Proxy address for HTTP requests (module downloads, fetch) |
| HTTPS_PROXY | Proxy address for HTTPS requests (module downloads, fetch) |
| NPM_CONFIG_REGISTRY | URL to use for the npm registry. |
| NO_COLOR | Set to disable color |
| NO_PROXY | Comma-separated list of hosts which do not use a proxy (module downloads, fetch) |
Loading