{
  "schema_version": 2,
  "id": "develop/ai/context-engine/lens/configure",
  "title": "Configure Lens",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/configure/",
  "summary": "Configure the Lens SDK settings, API keys, content capture, OpenTelemetry integration, and TLS.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T15:22:41-08:00",
  "page_type": "content",
  "content_hash": "8fe437b0eaac162d51faecccfc758cc3747917c51e26b1e248d56b44275e22ff",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Configure the Lens module of the Redis Iris software development kit (SDK) with environment variables, `lens.init()`, or `LensSettings`. Lens reads its environment variables once, at the first Lens or Iris service call. To apply a variable you set later, call `lens.init()`."
    },
    {
      "id": "settings",
      "title": "Settings",
      "role": "configuration",
      "text": "| Variable | `LensSettings` field | Description |\n| -------- | -------------------- | ----------- |\n| `IRIS_LENS_ENDPOINT` | `endpoint` | The Iris host, such as `https://iris.example.com`. The SDK sends turns to `/iris/data/v1beta1/lens/v1/traces` on it. Setting it turns Lens on. |\n| `IRIS_LENS_API_KEY` | `api_key` (read from the environment only) | The ingest key, sent with every export. |\n| `IRIS_LENS_AGENT_ID` | `agent_id` | The default agent ID for this process. `lens.turn(agent_id=...)` overrides it. |\n| `IRIS_LENS_SERVICE_NAME` | `service_name` | The service name recorded on every step. |\n| `IRIS_LENS_ENABLED` | `enabled` | `false` keeps Lens off, even when an endpoint is set. |\n| `IRIS_LENS_CAPTURE_CONTENT` | `capture_content` | Whether Lens captures prompts, completions, and retrieved text. Default `true`. |\n\nTo configure Lens in code, pass `LensSettings` to `Iris`. The key still comes from `IRIS_LENS_API_KEY`:\n\n[code example]\n\nA blank variable counts as unset, so its default applies. `IRIS_LENS_CAPTURE_CONTENT` is the exception: a blank value turns capture off."
    },
    {
      "id": "advanced-settings",
      "title": "Advanced settings",
      "role": "content",
      "text": "| Variable | Description |\n| -------- | ----------- |\n| `IRIS_LENS_HOST_SPANS` | `false` keeps Iris service steps out of your own tracer while Lens is off. Default `true`. |\n| `IRIS_LENS_HOST_CAPTURE_CONTENT` | Whether Iris service steps sent to your own tracer include text. Default `false`. |\n| `IRIS_LENS_AUTO_INSTRUMENT` | `false` turns off Iris service steps and keeps `lens.init()` from tracing model calls. |\n| `IRIS_LENS_INSTRUMENT_AGENT_MEMORY` | `false` turns off Agent Memory steps. |\n| `IRIS_LENS_INSTRUMENT_PLAYBOOK` | `false` turns off Agent Playbooks steps. |\n| `IRIS_LENS_INSTRUMENT_THREADS` | `false` keeps `lens.init()` from carrying turns across Python threads. |\n| `IRIS_LENS_OWN_PROVIDER` | `false` keeps Lens from installing a global OpenTelemetry tracer provider. |\n| `IRIS_LENS_DROP_SCOPES` | A comma-separated list of OpenTelemetry instrumentation scope names that Lens never exports. It replaces the default list, so include any defaults you want to keep. |\n| `IRIS_LENS_DROP_REDIS_COMMANDS` | A comma-separated list of Redis commands Lens never exports. |\n| `IRIS_LENS_STRICT` | `true` makes `lens.turn()` raise an error when it has no session ID. |\n| `IRIS_LENS_AUTH_HEADER` | The header that carries the ingest key. Default `Authorization`, as `Bearer <key>`. |\n| `IRIS_LENS_ALLOW_INSECURE` | `true` permits an `http://` endpoint that isn't a loopback address. |\n\nLens uses its own exporter. It reads no `OTEL_EXPORTER_OTLP_*` variables. Proxies and certificate bundles come from `HTTPS_PROXY`, `NO_PROXY`, and `SSL_CERT_FILE`."
    },
    {
      "id": "api-keys-and-scopes",
      "title": "API keys and scopes",
      "role": "content",
      "text": "Lens keys have one of three scopes:\n\n| Scope | Use it for |\n| ----- | ---------- |\n| `ingest` | Agents that send turns to Lens. |\n| `read` | People and tools that read turns, in the Lens user interface (UI) or with the read application programming interface (API). |\n| `full` | Both. |\n\nAgents send their key as `IRIS_LENS_API_KEY`. The read client reads its key from `LENS_API_KEY`. Give each agent its own ingest key and each reader a read key. If one agent's key leaks, you can revoke or rotate that key without interrupting your other agents. On Redis Cloud, [create keys in the console](https://redis.io/docs/latest/operate/iris/lens/create-lens#create-api-keys). Self-managed, your administrator [creates them](https://redis.io/docs/latest/operate/iris/lens/self-managed/authentication#create-api-keys)."
    },
    {
      "id": "control-content-capture",
      "title": "Control content capture",
      "role": "content",
      "text": "Set `IRIS_LENS_CAPTURE_CONTENT=false` to send no text to Lens. Lens also removes prompt and completion text that other instrumentation added, before export. See [content capture](https://redis.io/docs/latest/develop/ai/context-engine/lens/concepts#content-capture) for what Lens keeps."
    },
    {
      "id": "use-lens-with-your-existing-opentelemetry-setup",
      "title": "Use Lens with your existing OpenTelemetry setup",
      "role": "content",
      "text": "Lens is built on OpenTelemetry and works with the tracing your application already has:\n\n- If your application has a tracer provider, Lens adds its processor to it. Steps your application records inside a turn are exported to Lens as well.\n- If your application has no tracer provider, Lens installs one. To prevent that, set `IRIS_LENS_OWN_PROVIDER=false`.\n- Lens steps also reach your provider's other processors, so they appear in your existing observability tools.\n- While Lens is off, Iris service steps still go to your own tracer, without text. Your existing tools see Iris latency and errors with no Lens endpoint configured."
    },
    {
      "id": "connect-over-tls",
      "title": "Connect over TLS",
      "role": "content",
      "text": "Lens sends turns over Transport Layer Security (TLS), so use an `https://` endpoint. Lens verifies the server certificate and never follows redirects, so the key and captured content go only to the endpoint you set.\n\nFor local testing, `http://` works with loopback addresses such as `localhost`. To permit `http://` elsewhere, set `IRIS_LENS_ALLOW_INSECURE=true`."
    }
  ],
  "examples": [
    {
      "id": "settings-ex0",
      "language": "python",
      "code": "from redis_iris import Iris, IrisSettings\nfrom redis_iris.lens import LensSettings\n\nsettings = LensSettings(endpoint=\"<iris-host>\", agent_id=\"support-bot\")\niris = Iris(IrisSettings(lens=settings))",
      "section_id": "settings"
    }
  ]
}