From ce664f58e948f21d8e7f91b850d0e3ea11dca486 Mon Sep 17 00:00:00 2001 From: kiro-agent Date: Sun, 26 Jul 2026 08:20:53 +0000 Subject: [PATCH] docs: add client identification options (lib_name, client_info_tag) for Python Signed-off-by: kiro-agent --- astro.config.mjs | 1 + .../monitoring/client-identification.mdx | 127 ++++++++++++++++++ .../docs/reference/connection-options.mdx | 29 ++++ 3 files changed, 157 insertions(+) create mode 100644 src/content/docs/how-to/monitoring/client-identification.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 9bda7bc7..5d51116c 100755 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -187,6 +187,7 @@ export default defineConfig({ { label: "Monitoring", items: [ + "how-to/monitoring/client-identification", "how-to/monitoring/logging", "how-to/monitoring/open-telemetry", "how-to/monitoring/tracking-resources", diff --git a/src/content/docs/how-to/monitoring/client-identification.mdx b/src/content/docs/how-to/monitoring/client-identification.mdx new file mode 100644 index 00000000..3daab334 --- /dev/null +++ b/src/content/docs/how-to/monitoring/client-identification.mdx @@ -0,0 +1,127 @@ +--- +title: Client Identification +description: Customize the library name reported to Valkey for framework attribution and observability. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Frameworks and libraries that embed Valkey GLIDE often need to be identifiable in `CLIENT INFO` and `CLIENT LIST` output. This is useful for adoption tracking, observability, and debugging — letting operators see exactly which library or framework is responsible for each connection. + +## client_name vs lib_name + +Valkey exposes two separate identification fields per connection: + +| Option | Valkey command | Purpose | +|--------|---------------|---------| +| `client_name` | `CLIENT SETNAME` | Identifies the **application** (e.g. `"order-service"`) | +| `lib_name` / `client_info_tag` | `CLIENT SETINFO LIB-NAME` | Identifies the **library or framework** (e.g. `"GlidePy(my-framework:1.2.3)"`) | + +Use `client_name` to label your application instance. Use `lib_name` and `client_info_tag` when you are building a library or framework on top of GLIDE and want that layer to be visible in server diagnostics. + +## Configuration Options + +GLIDE provides two options for controlling the `LIB-NAME` value: + +- **`client_info_tag`** (recommended) — appends a parenthesized tag to the default library name, preserving GLIDE's identity. For example, setting `client_info_tag="my-framework:1.2.3"` produces `GlidePy(my-framework:1.2.3)`. +- **`lib_name`** — fully overrides the default library name. Use this only when you need complete control over the reported name. + +### Behavior Matrix + +| Configuration | Resulting `lib-name` (async) | Resulting `lib-name` (sync) | +|---|---|---| +| _(none)_ | `GlidePy` | `GlidePySync` | +| `client_info_tag="lmcache:1.2"` | `GlidePy(lmcache:1.2)` | `GlidePySync(lmcache:1.2)` | +| `lib_name="custom"` | `custom` | `custom` | +| `lib_name="custom"`, `client_info_tag="lmcache:1.2"` | `custom(lmcache:1.2)` | `custom(lmcache:1.2)` | + +## Examples + + + + **Async client (cluster mode):** + + ```python + from glide import ( + GlideClusterClient, + GlideClusterClientConfiguration, + NodeAddress + ) + + # Recommended: use client_info_tag to preserve GLIDE identity + config = GlideClusterClientConfiguration( + addresses=[NodeAddress("localhost", 6379)], + client_info_tag="my-framework:1.2.3", + ) + client = await GlideClusterClient.create(config) + # lib-name in CLIENT INFO: GlidePy(my-framework:1.2.3) + + # Full override (replaces the default library name entirely) + config = GlideClusterClientConfiguration( + addresses=[NodeAddress("localhost", 6379)], + lib_name="custom-lib", + ) + client = await GlideClusterClient.create(config) + # lib-name in CLIENT INFO: custom-lib + ``` + + **Sync client (standalone mode):** + + ```python + from glide import ( + GlideClient, + GlideClientConfiguration, + NodeAddress + ) + + config = GlideClientConfiguration( + addresses=[NodeAddress("localhost", 6379)], + client_info_tag="my-framework:1.2.3", + ) + client = GlideClient(config) + # lib-name in CLIENT INFO: GlidePySync(my-framework:1.2.3) + ``` + + + + :::note[Coming soon] + The `client_info_tag` option is not yet available in Java. Java already supports `libName` for overriding the library name, but the tag-append behavior will be added in a future release. + ::: + + + + :::note[Coming soon] + Client identification options (`lib_name` and `client_info_tag`) are not yet available in the Node.js client. Support is planned for a future release. + ::: + + + + :::note[Coming soon] + Client identification options (`lib_name` and `client_info_tag`) are not yet available in the Go client. + ::: + + + + :::note[Coming soon] + Client identification options (`lib_name` and `client_info_tag`) are not yet available in the PHP client. + ::: + + + + :::note[Coming soon] + Client identification options (`lib_name` and `client_info_tag`) are not yet available in the C# client. + ::: + + + +## Validation Rules + +The `client_info_tag` value **must not contain whitespace**. This constraint comes from the Valkey `CLIENT SETINFO` command, which does not allow spaces in values. If you pass a tag containing spaces, the client will reject it. + +Valid examples: +- `"my-framework:1.2.3"` +- `"lmcache:2.0"` +- `"analytics-sdk"` + +Invalid examples: +- `"my framework"` (contains a space) +- `"lmcache 1.2"` (contains a space) diff --git a/src/content/docs/reference/connection-options.mdx b/src/content/docs/reference/connection-options.mdx index 47e32dbf..4d127855 100644 --- a/src/content/docs/reference/connection-options.mdx +++ b/src/content/docs/reference/connection-options.mdx @@ -106,3 +106,32 @@ The following are the configuration references for each Glide clients: ``` + +## Client Identification Options + +GLIDE clients can customize the library name reported to the Valkey server via `CLIENT SETINFO LIB-NAME`. This is useful for frameworks and libraries built on top of GLIDE that want to be identifiable in `CLIENT INFO` and `CLIENT LIST` output. + +| Option | Description | Availability | +|--------|-------------|--------------| +| `lib_name` | Fully overrides the default library name (e.g. `GlidePy`) | Python | +| `client_info_tag` | Appends a parenthesized tag to the library name (e.g. `GlidePy(my-tag)`) | Python | +| `libName` | Overrides the default library name | Java | + +:::note +`client_info_tag` is currently Python-only. Java supports `libName` for overriding the library name but does not yet have the tag-append option. Node.js, Go, PHP, and C# do not yet support these options. +::: + +### Example + +```python +from glide import GlideClusterClientConfiguration, NodeAddress + +# Append a framework tag while preserving GLIDE identity +config = GlideClusterClientConfiguration( + addresses=[NodeAddress("localhost", 6379)], + client_info_tag="my-framework:1.2.3", +) +# Resulting lib-name: GlidePy(my-framework:1.2.3) +``` + +For detailed usage, the behavior matrix, and validation rules, see [Client Identification](/how-to/monitoring/client-identification/).