Skip to content

docs: add settings documentation to otel.py and generate documentation. Fixes #751 #817

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

Merged
aldbr merged 4 commits into from
Mar 25, 2026
Merged

docs: add settings documentation to otel.py and generate documentation. Fixes #751 #817

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e7d50b4
docs: add settings documentation to otel.py and dynamic env variables…
martynia Mar 3, 2026
6cc7383
fix: remove a change in pixi.toml
martynia Mar 19, 2026
20a7288
docs: remove duplicate documentation
martynia Mar 19, 2026
64b0660
docs: move bits around
martynia Mar 19, 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
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,4 +99,4 @@ repos:
entry: pixi run -e default python scripts/generate_settings_docs.py
language: system
pass_filenames: false
files: ^(diracx-.*/src/diracx/.*/settings\.py|docs/.*\.j2|docs/templates/.*\.jinja|scripts/generate_settings_docs\.py)$
files: ^(diracx-.*/src/diracx/.*/settings\.py|diracx-routers/src/diracx/routers/otel\.py|docs/.*\.j2|docs/templates/.*\.jinja|scripts/generate_settings_docs\.py)$
25 changes: 22 additions & 3 deletions diracx-routers/src/diracx/routers/otel.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,34 @@
class OTELSettings(ServiceSettingsBase):
"""Settings for the Open Telemetry Configuration."""

model_config = SettingsConfigDict(env_prefix="DIRACX_OTEL_")
model_config = SettingsConfigDict(
env_prefix="DIRACX_OTEL_", use_attribute_docstrings=True
)

enabled: bool = False
"""
Determines whether OpenTelemetry is enabled.
"""

application_name: str = "diracx"
"""
The name of the application for OpenTelemetry.
"""

grpc_endpoint: str = ""
"""
The gRPC endpoint for the OpenTelemetry collector.
"""

grpc_insecure: bool = True
# headers to pass to the OTEL Collector
# e.g. {"tenant_id": "lhcbdiracx-cert"}
"""
Whether to use an insecure gRPC connection for the OpenTelemetry collector.
"""

headers: Optional[dict[str, str]] = None
"""
A JSON-encoded dictionary of headers to pass to the OpenTelemetry collector, e.g. {"tenant_id": "lhcbdiracx-cert"}.
"""


def instrument_otel(app: FastAPI) -> None:
Expand Down
39 changes: 39 additions & 0 deletions docs/admin/reference/env-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,21 @@

*This page is auto-generated from the settings classes in `diracx.core.settings`.*

## Core

### `DIRACX_CONFIG_BACKEND_URL`

The URL of the configuration backend.

### `DIRACX_SERVICE_DOTENV`

The variable points to .env files where configuration may be placed. There could be more than one file, with suffixes
\_X, where X is a number. The files will be loaded in order.

### `DIRACX_SERVICE_JOBS_ENABLED`

Determines whether the jobs service is enabled.

## AuthSettings

Settings for the authentication service.
Expand Down Expand Up @@ -123,6 +138,10 @@ Set of security properties available in this DIRAC installation.
These properties define various authorization capabilities and are used
for access control decisions. Defaults to all available security properties.

### `DIRACX_LEGACY_EXCHANGE_HASHED_API_KEY`

The hashed API key for the legacy exchange endpoint.

## SandboxStoreSettings

Settings for the sandbox store.
Expand Down Expand Up @@ -199,6 +218,16 @@ Maximum number of concurrent DB delete chunks during cleaning.

Controls parallelism of database DELETE operations.

## Databases

### `DIRACX_DB_URL_<db_name>`

The URL for the SQL database `<db_name>`.

### `DIRACX_OS_DB_<db_name>`

A JSON-encoded dictionary of connection keyword arguments for the OpenSearch database `<db_name>`.

## OTELSettings

Settings for the Open Telemetry Configuration.
Expand All @@ -207,18 +236,28 @@ Settings for the Open Telemetry Configuration.

*Optional*, default value: `False`

Determines whether OpenTelemetry is enabled.

### `DIRACX_OTEL_APPLICATION_NAME`

*Optional*, default value: `diracx`

The name of the application for OpenTelemetry.

### `DIRACX_OTEL_GRPC_ENDPOINT`

*Optional*, default value: \`\`

The gRPC endpoint for the OpenTelemetry collector.

### `DIRACX_OTEL_GRPC_INSECURE`

*Optional*, default value: `True`

Whether to use an insecure gRPC connection for the OpenTelemetry collector.

### `DIRACX_OTEL_HEADERS`

*Optional*, default value: `None`

A JSON-encoded dictionary of headers to pass to the OpenTelemetry collector, e.g. {"tenant_id": "lhcbdiracx-cert"}.
24 changes: 24 additions & 0 deletions docs/admin/reference/env-variables.md.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,33 @@
# List of environment variables

*This page is auto-generated from the settings classes in `diracx.core.settings`.*
## Core

### `DIRACX_CONFIG_BACKEND_URL`
The URL of the configuration backend.

### `DIRACX_SERVICE_DOTENV`
The variable points to .env files where configuration may be placed. There could be more than one file, with suffixes
_X, where X is a number. The files will be loaded in order.

### `DIRACX_SERVICE_JOBS_ENABLED`
Determines whether the jobs service is enabled.

{{ render_class('AuthSettings') }}

### `DIRACX_LEGACY_EXCHANGE_HASHED_API_KEY`
The hashed API key for the legacy exchange endpoint.

{{ render_class('SandboxStoreSettings') }}

Comment on lines +20 to +24
Copy link
Copy Markdown
Contributor

@aldbr aldbr Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why here and not between ##Databases and SandboxStoreSettings?

Copy link
Copy Markdown
Contributor Author

@martynia martynia Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently Database is after SandboxStore, if I put them between, they would belong to SandboxStore. Should those setting have their own section or sections? The dotinv one looks like a major one, shouldn't it go on top ? The same is true with DIRACX_CONFIG_BACKEND_URL. Which section should this go to ?

Copy link
Copy Markdown
Contributor

@aldbr aldbr Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Core section is good. Can you also remove the duplicated DIRACX_SERVICE_DOTENV please?

Copy link
Copy Markdown
Contributor Author

@martynia martynia Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Copy link
Copy Markdown
Contributor

@aldbr aldbr Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok sorry, one last comment, then it's ok 😅
I think we should move DIRACX_SERVICE_JOBS_ENABLED in the Core section and DIRACX_LEGACY_EXCHANGE_HASHED_API_KEY should likely go before SandboxStoreSettings as you did originally (sorry 😅 )

## Databases

### `DIRACX_DB_URL_<db_name>`

The URL for the SQL database `<db_name>`.

### `DIRACX_OS_DB_<db_name>`

A JSON-encoded dictionary of connection keyword arguments for the OpenSearch database `<db_name>`.

Comment thread
aldbr marked this conversation as resolved.
{{ render_class('OTELSettings') }}
Loading