Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fintegrations%2Fai-observability%2Fopenai%2Fcodex.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fintegrations%2Fai-observability%2Fopenai%2Fcodex.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Codex integration with Coralogix

Monitor Codex across your organization: active users, credits and cost, token usage, models, tool calls, code impact, code review activity, and the repositories sessions work in. Usage data arrives from OpenAI's APIs with no developer-machine setup; a small repository-tracking hook on developer machines adds the repository dimension. Once connected, the data populates the Codex dashboard in **AI Center**, under **Code Agents**.

## Overview[​](#overview "Direct link to Overview")

Codex telemetry comes from up to 3 sources. Each source is optional and independently unlocks its own part of the dashboard, so you can start with one and add the others later:

* **Codex analytics**: one analytics API key per ChatGPT Enterprise workspace, in the OpenAI Usage & Cost integration. Unlocks workspace-wide usage: credits, list cost, tokens, models, clients, threads, and Codex code review activity, covering every Codex surface, including the CLI, IDE extension, the ChatGPT desktop app, cloud tasks, and code review.
* **Compliance API**: one Compliance API key per workspace, in the same integration. Unlocks per-user activity detail: tokens by reasoning effort, tool call breakdowns with success and failure rates, session turns, and active time.
* **Repository-tracking hook**: a small PostToolUse hook deployed to developer machines. Unlocks repository attribution: which repositories and branches each session worked in, and the commits, pull requests, and lines each session produced.

The Codex analytics and Compliance API sources poll OpenAI's APIs and collect the results as metrics and logs in Coralogix. The hook runs inside Codex on each developer machine and sends its repository metrics directly to your Coralogix endpoint; it does not pass through OpenAI's servers.

## Supported environments[​](#supported-environments "Direct link to Supported environments")

* **Codex analytics and Compliance API**: every Codex surface, with no setup on developer machines.
* **Repository-tracking hook**: macOS and Windows. Coralogix validated it with Codex CLI `0.149.1` and the ChatGPT desktop app (bundling `codex-cli 0.149.0-alpha.4.1`); the hooks feature is stable as of Codex `0.154`.

## What you need[​](#what-you-need "Direct link to What you need")

* A ChatGPT Enterprise workspace with Codex, for the Codex analytics and Compliance API sources. A ChatGPT Enterprise workspace owner must create the restricted API keys.
* Permission to create integrations in your Coralogix account. See [Permissions](#permissions).
* To see every detail on the dashboard, read access to the raw Codex datasets, which are restricted by default. See [Raw records](#raw-records).
* For the repository-tracking hook: a Coralogix **Send-Your-Data [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key.md)** and network access from developer machines to `https://ingress.eu2.coralogix.com` on port `443`. Use the domain selector at the top of this page to select your region.

## Create API keys in the ChatGPT admin console[​](#create-api-keys-in-the-chatgpt-admin-console "Direct link to Create API keys in the ChatGPT admin console")

1. In the [ChatGPT admin console](https://admin.openai.com), create a restricted admin key per ChatGPT Enterprise workspace for each source you want:

   * **Codex analytics API key**: one per workspace. Requires the `codex.enterprise.analytics.read` scope, which OpenAI Support grants on request. Plan for the support-ticket lead time.
   * **Compliance API key**: one per workspace, created by a workspace owner (not an admin) under **Credentials**, then **Admin keys**, then **Restricted**, with the `chatgpt.enterprise.compliance_logs_platform.read` and `chatgpt.enterprise.compliance_export.read` scopes. An analytics key that carries both compliance scopes works too.

2. Copy each key and store it securely. OpenAI shows a key only once, at creation time.

3. Collect the workspace ID of each workspace: the ChatGPT Enterprise workspace UUID shown in the ChatGPT admin console.

4. Optional: collect your ChatGPT Enterprise organization ID, the `org-...` ID from the ChatGPT Enterprise admin console. It unlocks the organization's credit costs and requires at least one Compliance API key. This is a different ID from the API Platform organization ID.

## Set up[​](#set-up "Direct link to Set up")

The OpenAI Usage & Cost integration collects the Codex analytics and Compliance API sources. It is the same integration that collects the [API Platform](https://coralogix.com/docs/integrations/ai-observability/openai/api-platform.md) telemetry, so if your organization already runs it, edit the existing deployment and add the Codex credentials rather than creating a second one.

1. From your Coralogix toolbar, navigate to **Data Flow**, then **Integrations**. Select **OpenAI Usage & Cost**, then select **Connect**.

2. Select **Add New**, or open your existing deployment to edit it.

3. Define the integration settings. Provide at least one credential; each one enables its own set of data:

   <!-- -->

   * **Integration name**: a meaningful name for this integration. Defaults to `OpenAI Usage & Cost`.
   * **Application name**: the Coralogix application name for all data from this integration. Defaults to `openai-integration`.
   * **Subsystem name**: optional. When set, all data ingests under this single subsystem instead of each source's default.
   * **Admin API key**, under **OpenAI API Platform**: optional. Unlocks the organization-level [API Platform](https://coralogix.com/docs/integrations/ai-observability/openai/api-platform.md) telemetry. Not required for Codex.
   * **Codex analytics**, under **Codex and ChatGPT**: one **Workspace ID** and **Codex analytics API key** pair per workspace. Select **Add workspace** for each additional workspace.
   * **ChatGPT and Codex compliance**, under **Codex and ChatGPT**: one **Workspace ID** and **Compliance API key** pair per workspace, and optionally the ChatGPT Enterprise organization ID, which is required to collect the credit costs your company pays.

4. Select **Create**, or **Save** when editing. Coralogix checks that each key is accepted before saving.

Workspace IDs must be unique within each section, and every row needs both a workspace ID and a key. When you edit the workspace rows of an existing deployment, the stored keys for that section are replaced, so enter every key in that section again.

## Application name and subsystem[​](#application-name-and-subsystem "Direct link to Application name and subsystem")

Coralogix routes the hook's metrics by the `CX-Application-Name` and `CX-Subsystem-Name` headers in the hook's configuration. For Codex, we recommend:

| Header                | Recommended value                                                     | Why                                                                                                                                        |
| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `CX-Application-Name` | `codex`                                                               | Keeps the hook's metrics together with the other Codex data.                                                                               |
| `CX-Subsystem-Name`   | The team or rollout-group name, for example, `platform` or `data-eng` | Groups the hook's data by team or rollout group in Coralogix. The Codex dashboard filters by workspace, user, and model, not by subsystem. |

The OpenAI-side sources use the application and subsystem names you set in the integration.

## Repository breakdown[​](#repository-breakdown "Direct link to Repository breakdown")

The OpenAI-side sources report who used Codex, with which models, and at what cost, but never which Git repository a session worked in. The Coralogix repository-tracking hook adds that dimension: it resolves the Git repository for the session's working directory and reports it to Coralogix. AI Center joins the hook's session ID to the session identifiers in the Compliance data, attributes sessions and usage to repositories, and separates **Managed** repositories from **Unmanaged** ones.

### How it works[​](#how-it-works "Direct link to How it works")

The hook is a Codex [PostToolUse hook](https://developers.openai.com/codex/hooks): a small script that Codex runs after each tool call. On macOS the hook is a shell script (`codex-repo-tracker.sh`); on Windows it's a PowerShell script (`codex-repo-tracker.ps1`). Both use only tools that ship with the operating system and read their Coralogix configuration from Codex's own configuration, so there are no separate hook credentials to manage.

* On each tool call, the hook emits the gauge metric `codex_session_repo_info` with `session_id` and `repository_name` labels. The metric itself carries no user identity; per-user and per-model repository breakdowns come from joining the session ID to the Compliance data in AI Center.
* The hook also reports the branch each session worked on, and git-verified running totals per session and repository: commits, pull requests opened, and lines added and removed. Commits are verified against Git history and filtered to the machine's own Git identity, never parsed out of command text, so the counts understate rather than invent.
* It bounds every Git call to 5 seconds and swallows all errors, so it can never disturb or stall a session.

### What you need[​](#what-you-need-1 "Direct link to What you need")

* The hook script for each platform, `hooks/codex-repo-tracker.sh` (macOS) and `hooks/codex-repo-tracker.ps1` (Windows), from the [Coralogix AI agent instrumentation repository](https://github.com/coralogix/ai-agent-instrumentation/tree/master/codex). The install steps on this page run from the repository's `codex` directory:

  ```
  git clone https://github.com/coralogix/ai-agent-instrumentation.git

  cd ai-agent-instrumentation/codex
  ```

* A Coralogix Send-Your-Data API key.

* No extra runtime. The macOS hook uses `/bin/sh`, `plutil`, and `curl`; the Windows hook uses Windows PowerShell 5.1.

* **`git`** is optional. The hook calls `git` to resolve repository names; without it, that machine reports `repository_name="unknown"`.

### Per-operating-system values[​](#per-operating-system-values "Direct link to Per-operating-system values")

| Operating system     | Hook script              | Deploy path                                                   | Built-in runtime            |
| -------------------- | ------------------------ | ------------------------------------------------------------- | --------------------------- |
| macOS, one developer | `codex-repo-tracker.sh`  | `/usr/local/bin/codex-repo-tracker.sh`                        | `/bin/sh`, `plutil`, `curl` |
| macOS, Jamf fleet    | `codex-repo-tracker.sh`  | `/usr/local/coralogix/codex-hooks/codex-repo-tracker.sh`      | `/bin/sh`, `plutil`, `curl` |
| Windows              | `codex-repo-tracker.ps1` | `C:\ProgramData\Coralogix\codex-hooks\codex-repo-tracker.ps1` | Windows PowerShell 5.1      |

### Configure the hook's Coralogix destination[​](#configure-the-hooks-coralogix-destination "Direct link to Configure the hook's Coralogix destination")

The hook reads its Coralogix endpoint and API key from Codex's own configuration. On macOS, it reads the managed preferences first, then the user's `~/.codex/config.toml`. On Windows, it reads the user's `%USERPROFILE%\.codex\config.toml` first, then `%ProgramData%\OpenAI\Codex\config.toml`. Any value missing from the configuration falls back to the `CX_OTLP_ENDPOINT`, `CX_API_KEY`, `CX_APPLICATION_NAME`, or `CX_SUBSYSTEM_NAME` environment variable.

Merge this block into `~/.codex/config.toml` (`%USERPROFILE%\.codex\config.toml` on Windows), replacing `<YOUR_CX_API_KEY>` with a literal value. The endpoint shows the region you select at the top of this page; the hook swaps the `/v1/logs` path for `/v1/metrics` on its own:

```
[otel.exporter.otlp-http]

endpoint = "https://ingress.eu2.coralogix.com/v1/logs"

protocol = "binary"



[otel.exporter.otlp-http.headers]

"Authorization" = "Bearer <YOUR_CX_API_KEY>"

"CX-Application-Name" = "codex"

"CX-Subsystem-Name" = "codex-sessions"
```

Codex also exports its own logs

`[otel.exporter.otlp-http]` is Codex's own log-export block, so while it is present Codex also streams its session log events to the same Coralogix endpoint. The Codex dashboard does not require those logs. To configure the hook without them, set the `CX_*` environment variables instead; note that environment variables reach Codex CLI in a terminal but not the ChatGPT desktop app, which is launched from the Dock and reads only the configuration files.

Do not append duplicate `[otel]` or header tables to an existing TOML file; duplicate table names make the configuration invalid. Back up `~/.codex/config.toml` before merging.

### Deploy to a macOS fleet with Jamf[​](#deploy-to-a-macos-fleet-with-jamf "Direct link to Deploy to a macOS fleet with Jamf")

Jamf delivers two things to every Mac: the hook script, through a policy, and a configuration profile that registers the hook and sets its Coralogix destination. Codex treats the profile as managed configuration, so developers install and approve nothing.

1. Add the installer script to Jamf Pro. Select **Settings**, then **Computer management**, then **Scripts**, then **New**, and paste the contents of [`codex/hooks/jamf-install-hook.sh`](https://github.com/coralogix/ai-agent-instrumentation/blob/master/codex/hooks/jamf-install-hook.sh) from the Coralogix AI agent instrumentation repository. The script installs the hook at `/usr/local/coralogix/codex-hooks/codex-repo-tracker.sh`.

2. Create a policy that runs the script. Select **Computers**, then **Policies**, then **New**, and add the script in the **Scripts** payload.

3. Save the completed block from [Configure the hook's Coralogix destination](#configure-the-hooks-coralogix-destination) as `codex-managed.toml`, then build the profile's property list from the repository's `codex` directory:

   ```
   ./hooks/jamf-build-profile.sh hooks/managed-requirements.example.toml codex-managed.toml > com.openai.codex.plist
   ```

   The property list holds your Send-Your-Data key, so keep it out of source control.

4. Create a configuration profile and add an **Application & Custom Settings** payload. Select **Upload**, set the preference domain to `com.openai.codex`, and upload `com.openai.codex.plist`.

5. Scope the policy and the profile to one test Mac. Scope the policy first, or both at the same time: Codex loads managed hooks only from a hook directory that already exists.

6. On the test Mac, restart Codex and complete a tool call inside a Git repository. Confirm that Codex starts without a `hooks need review` prompt, and that `codex_session_repo_info` appears in Metrics Explorer.

7. Scope the policy and the profile to the rest of your Macs.

Developers only restart Codex; the hook reports from their next session. After the rollout:

* To update the hook, rerun the policy.
* To rotate the API key or change the endpoint, rebuild the property list and update the profile.
* On a Mac where a developer also installed the hook per user, remove that entry from `~/.codex/hooks.json`. Both copies write to the same state file, which skews the commit and line counts.

### Deploy to a Windows fleet[​](#deploy-to-a-windows-fleet "Direct link to Deploy to a Windows fleet")

Your device-management tool, such as Microsoft Intune, delivers three files to every machine. Codex reads the two under `%ProgramData%\OpenAI\Codex` as machine-wide configuration, so developers install and approve nothing.

1. Deploy [`codex/hooks/codex-repo-tracker.ps1`](https://github.com/coralogix/ai-agent-instrumentation/blob/master/codex/hooks/codex-repo-tracker.ps1) from the Coralogix AI agent instrumentation repository to `C:\ProgramData\Coralogix\codex-hooks\codex-repo-tracker.ps1`.

2. Deploy the completed block from [Configure the hook's Coralogix destination](#configure-the-hooks-coralogix-destination) as `%ProgramData%\OpenAI\Codex\config.toml`. The file holds your Send-Your-Data key, so keep it out of source control. A developer's own `%USERPROFILE%\.codex\config.toml` overrides this file, for both Codex and the hook.

3. Deploy [`codex/hooks/managed-requirements.example.toml`](https://github.com/coralogix/ai-agent-instrumentation/blob/master/codex/hooks/managed-requirements.example.toml) from the same repository as `%ProgramData%\OpenAI\Codex\requirements.toml`. This file registers the hook, and Codex picks its Windows entries automatically. Deploy it after the script, or both at the same time: Codex loads managed hooks only from a hook directory that already exists.

4. On one test machine, restart Codex and complete a tool call inside a Git repository. Confirm that Codex starts without a `hooks need review` prompt, and that `codex_session_repo_info` appears in Metrics Explorer.

5. Deploy the three files to the rest of your machines.

Developers only restart Codex; the hook reports from their next session. After the rollout:

* To update the hook, redeploy `codex-repo-tracker.ps1`.
* To rotate the API key or change the endpoint, redeploy `config.toml`.
* On a machine where a developer also installed the hook per user, remove that entry from `%USERPROFILE%\.codex\hooks.json`. Both copies write to the same state file, which skews the commit and line counts.

### Install for one developer[​](#install-for-one-developer "Direct link to Install for one developer")

1. Copy your platform's hook script to its stable path.

   On macOS:

   ```
   sudo cp hooks/codex-repo-tracker.sh /usr/local/bin/codex-repo-tracker.sh

   sudo chmod 755 /usr/local/bin/codex-repo-tracker.sh
   ```

   On Windows (PowerShell as administrator):

   ```
   New-Item -ItemType Directory -Force "C:\ProgramData\Coralogix\codex-hooks" | Out-Null

   Copy-Item hooks\codex-repo-tracker.ps1 "C:\ProgramData\Coralogix\codex-hooks\codex-repo-tracker.ps1"
   ```

2. Register the hook by merging the repository's `hooks/user-hooks.example.json` into `~/.codex/hooks.json` (`%USERPROFILE%\.codex\hooks.json` on Windows), creating the file if it does not exist. The example registers one PostToolUse command per platform; Codex picks the one matching the operating system.

3. Start a new Codex session. Codex shows a one-time `hooks need review` prompt for hooks registered in `hooks.json`; review and approve it. The hook reports a repository the first time a tool call completes.

When editing `hooks.json` by hand, four schema details fail silently or with a cryptic error: event names are PascalCase (`PostToolUse`), `matcher` must be a valid regular expression (`".*"`, not `"*"`), the timeout key is `timeout` in seconds, and the registration lives in `~/.codex/hooks.json`, never inside `config.toml`. Any later edit to `hooks.json` changes the hook's hash and triggers the review prompt again.

### Classify repositories as Managed or Unmanaged[​](#classify-repositories-as-managed-or-unmanaged "Direct link to Classify repositories as Managed or Unmanaged")

Repository names alone don't tell AI Center which repositories belong to your company. In **Settings → AI Center → Code agent**, configure the **Organizations** that own your repositories. Sessions on a matched repository are labeled **Managed**, and everything else is **Unmanaged**. Until you configure an Organization, every repository appears as Unmanaged.

For the steps and the full classification rules, see [Classify repositories as Managed or Unmanaged](https://coralogix.com/docs/user-guides/ai/code-agents/repository-breakdown.md#classify-repositories).

## View in AI Center[​](#view-in-ai-center "Direct link to View in AI Center")

Navigate to **AI Center > Code Agents > Codex**. The dashboard covers activity, cost, and code impact, and fills according to the sources you connected:

* Usage, credits, list cost, tokens, models, clients, and Codex code review activity come from the Codex analytics source, broken down by workspace, user, model, and client.
* Tokens by reasoning effort, the tool call breakdown, session turns, and run time come from the Compliance API source.
* The repository views, including per-repository users, activity, and code impact, come from the repository-tracking hook.

Filter the dashboard by workspace, user, or model to narrow every widget to the same scope. Select a user, tool, client, or repository row to open its drawer with the matching detail.

## Validate the integration[​](#validate-the-integration "Direct link to Validate the integration")

After setup, confirm each source independently:

1. In Coralogix, navigate to **Metrics Explorer** and query `openai_analytics_codex_credits`. Analytics data is daily, so allow up to a day after setup for the first samples.

2. Query the Compliance API tokens. Compliance collection starts with the previous 24 hours, so recent activity appears shortly after setup:

   ```
   sum by (token_type) (max_over_time(openai_compliance_codex_tokens_total[24h]))
   ```

3. After a Codex session touches a Git repository, query `codex_session_repo_info`. The hook returns one series per session and repository.

4. Navigate to **AI Center > Code Agents > Codex** and confirm the usage widgets and the repository views populate.

## Data reference[​](#data-reference "Direct link to Data reference")

### Metrics[​](#metrics "Direct link to Metrics")

The OpenAI Usage & Cost integration writes Codex analytics under the `openai_analytics_codex_` prefix and Compliance API data under the `openai_compliance_` prefix. Analytics series carry the workspace and the UTC day of the source data as labels, with per-user, per-model, and per-client variants.

Show Codex analytics metrics

| Metric                                                                                                                                              | What it tracks                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `openai_analytics_codex_credits`                                                                                                                    | Codex credits consumed, per workspace, user, and day. |
| `openai_analytics_codex_cost_usd`                                                                                                                   | List-price cost in USD derived from usage.            |
| `openai_analytics_codex_model_credits`                                                                                                              | Credits split by model.                               |
| `openai_analytics_codex_cached_text_input_tokens`, `openai_analytics_codex_uncached_text_input_tokens`, `openai_analytics_codex_text_output_tokens` | Token usage by type, with per-model variants.         |
| `openai_analytics_codex_threads`, `openai_analytics_codex_turns`                                                                                    | Conversation volume.                                  |
| `openai_analytics_codex_lines`                                                                                                                      | Lines of code attributed to Codex.                    |
| `openai_analytics_codex_review_comments_by_priority`, `openai_analytics_codex_review_reactions_by_type`                                             | Codex code review activity.                           |

Show Compliance API metrics

| Metric                                        | What it tracks                                               |
| --------------------------------------------- | ------------------------------------------------------------ |
| `openai_compliance_codex_tokens_total`        | Tokens by type and reasoning effort, per user and workspace. |
| `openai_compliance_codex_tool_calls_total`    | Tool calls by tool and outcome.                              |
| `openai_compliance_codex_session_turns_total` | Session turns.                                               |
| `openai_compliance_events_total`              | Compliance events collected, by event type.                  |

The compliance counters hold a running total per series and UTC day. Read a window's total with `max_over_time` per series and sum the results; `sum_over_time` and `increase` count events more than once. Data collected before October 30, 2026 holds one sample per event instead, and the AI Center dashboard reads both forms.

### Labels[​](#labels "Direct link to Labels")

Show label reference

| Label                                     | On                              | Meaning                                                  |
| ----------------------------------------- | ------------------------------- | -------------------------------------------------------- |
| `workspace_id`                            | Analytics and Compliance series | The ChatGPT Enterprise workspace.                        |
| `date`                                    | Analytics and Compliance series | The UTC day the value describes.                         |
| `user_id`, `user_email`                   | Per-user series                 | The member the value belongs to.                         |
| `client_id`                               | Per-client series               | The Codex client the usage came from.                    |
| `model`, `token_type`, `reasoning_effort` | Compliance token series         | The model, the token category, and the reasoning effort. |
| `tool_name`, `tool_type`, `status`        | Compliance tool call series     | The tool and the outcome of the call.                    |
| `priority`                                | Code review series              | The priority of a review comment.                        |
| `session_id`, `repository_name`           | Hook series                     | The Codex session and the repository it worked in.       |

### Repository hook metrics[​](#repository-hook-metrics "Direct link to Repository hook metrics")

All hook metrics are gauges keyed by `session_id` and `repository_name`. The session ID joins to the session identifiers in the Compliance data, which is how AI Center attributes repositories to users and usage.

| Metric                                                     | What it tracks                                                                                                                                                |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `codex_session_repo_info`                                  | The session worked in this repository. Inside a Codex sub-agent, the point also carries an `agent_id` label, so sub-agent activity joins to repositories too. |
| `codex_session_branch_info`                                | The branch the session was on, as a `branch_name` label. Branch names are unbounded free text, so bucket them before charting.                                |
| `codex_session_commits`                                    | Cumulative commits the session made in this repository, verified against Git.                                                                                 |
| `codex_session_prs_opened`                                 | Cumulative pull requests the session opened from this repository.                                                                                             |
| `codex_session_lines_added`, `codex_session_lines_removed` | Cumulative lines added and removed by the session's counted commits.                                                                                          |

The counters understate rather than invent: uncommitted work and a commit made as the session's final action are not counted, and no commit is ever counted twice.

### Raw records[​](#raw-records "Direct link to Raw records")

Besides metrics, the integration writes the records it collects to predefined datasets in the `default` dataspace. Query them with DataPrime to build your own [Custom Dashboards](https://coralogix.com/docs/user-guides/custom-dashboards/introduction.md) and alerts beyond the built-in Codex dashboard; each dataset page lists its fields and includes a starter query:

| Source          | Dataset                                                                                                                                           | What it holds                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Codex analytics | [`ai.raw.openai.codex.analytics_logs`](https://coralogix.com/docs/user-guides/data-layer/default-dataspace/ai-raw-openai-codex-analytics-logs.md) | Daily Codex usage per user and workspace, and Codex code review activity.                                      |
| Compliance API  | [`ai.raw.openai.compliance_logs`](https://coralogix.com/docs/user-guides/data-layer/default-dataspace/ai-raw-openai-compliance-logs.md)           | Codex events, tasks, and environments in the `openai.compliance.codex` streams, alongside the ChatGPT records. |

The dashboard reads the analytics dataset for Codex code review on GitHub: OpenAI reports that usage on a workspace row with no user, which the metrics leave out. Without read access to the dataset, that usage is missing from the totals.

These datasets are restricted by default. To let more users query them, see [Access control](https://coralogix.com/docs/user-guides/data-layer/dataset-management/access-control.md).

## Limits and behavior[​](#limits-and-behavior "Direct link to Limits and behavior")

* **Key check on save.** Coralogix checks that each key is accepted when you save. A wrong organization ID or a missing key permission surfaces later as an error in the integration status. If the check runs out of time because there are many keys, save again; this does not mean a key is invalid.
* **Initial backfill.** Compliance collection starts with the last 24 hours of activity. There is no older history.
* **Interruptions.** If compliance collection is interrupted for more than 48 hours, it stops with an error; contact Support to resume it.
* **Daily analytics.** Analytics usage arrives as daily, per-workspace data, so the dashboard fills in day by day rather than in real time.

## Troubleshoot[​](#troubleshoot "Direct link to Troubleshoot")

Analytics or Compliance metrics do not appear

Cause: OpenAI rejected a key, a key lacks a scope, or the data has not arrived yet.

Fix:

* Open the integration in **Data Flow**, then **Integrations**, and check its status. A key check that failed after save names the workspace and the OpenAI error there.
* For analytics, confirm the key carries the `codex.enterprise.analytics.read` scope. OpenAI Support grants the scope on request, and a key created before the grant stays scopeless.
* For compliance, confirm a workspace owner created the key with both compliance scopes, and that the workspace ID is the ChatGPT Enterprise workspace UUID.
* If credit costs are missing, add the ChatGPT Enterprise organization ID to the integration. It requires at least one Compliance API key pair.
* Analytics data is daily: a new deployment shows its first analytics samples within about a day.
* If compliance collection was interrupted for more than 48 hours, it stops with an error in the integration status; contact Support to resume it.

After fixing a credential, save the integration again; the save re-runs the key check.

The repository views are empty

Cause: the repository views require the repository-tracking hook, and the hook fails silently by design.

Fix:

* Confirm `codex_session_repo_info` exists in Metrics Explorer. If it does not, the hook is not reporting.
* Confirm the hook's configuration resolves on that machine: the `[otel.exporter.otlp-http]` block in the managed configuration or the user's `config.toml`, or the `CX_*` environment variables. Without an endpoint and key, the hook exits without sending.
* For a per-user install, confirm the hook was approved: approval state lives in `~/.codex/config.toml` under `[hooks.state]` with two separate flags, `trusted_hash` and `enabled`. A hook can be trusted yet disabled, which is a silent no-op that looks exactly like a broken hook.
* Confirm the registration file is `~/.codex/hooks.json` with a PascalCase event name (`PostToolUse`) and a regular-expression matcher (`".*"`). Any edit to the file re-triggers the review prompt.
* If the metric reports `repository_name="unknown"`, `git` is not installed or the session's working directory is not inside a Git repository.
* To isolate configuration from delivery, run the hook by hand with its `--otlp-endpoint` and `--otlp-auth` flags and a sample event; the repository's `hooks/test-hook-local.sh` does this and prints the exact metric query to check.
* Check firewall, DNS, proxy, and TLS inspection rules for the Coralogix ingress host on port `443`, and in **Metrics Usage** enable the **Blocked** view and search for `codex_session_` metrics.

After fixing the configuration, registration, or approval, start a new Codex session and complete a tool call; the hook reports only when a tool call finishes.

## Permissions[​](#permissions "Direct link to Permissions")

To set up this integration, your Coralogix account must have the following permissions:

| Permission                | Description                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| `INTEGRATIONS:READCONFIG` | View deployed integrations.                                                                    |
| `INTEGRATIONS:DEPLOY`     | Deploy, undeploy, and update integrations. The Data Admin and Platform Admin roles include it. |

For details, see [Roles and permissions](https://coralogix.com/docs/user-guides/aaa/access-control/permissions.md).

## Next steps[​](#next-steps "Direct link to Next steps")

Set up the [ChatGPT integration](https://coralogix.com/docs/integrations/ai-observability/openai/chatgpt.md) to monitor ChatGPT Enterprise usage, cost, and seats with the same OpenAI Usage & Cost integration.