Open in ChatGPTOpen in Claude

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

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

• 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

• 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.
• To see every detail on the dashboard, read access to the raw Codex datasets, which are restricted by default. See Raw records.
• For the repository-tracking hook: a Coralogix Send-Your-Data API key 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

1. In the ChatGPT admin console, 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

The OpenAI Usage & Cost integration collects the Codex analytics and Compliance API sources. It is the same integration that collects the API Platform 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 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

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

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

The hook is a Codex PostToolUse hook: 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

• 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. 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

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

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

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 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 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

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 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 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 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

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

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.

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

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

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.

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

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

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 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	Daily Codex usage per user and workspace, and Codex code review activity.
Compliance API	ai.raw.openai.compliance_logs	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.

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

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

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.

Next steps

Set up the ChatGPT integration to monitor ChatGPT Enterprise usage, cost, and seats with the same OpenAI Usage & Cost integration.