Skip to main content

Review tool usage

The Tool Usage screen in the console summarizes tool calls through the Connector Gateway, so you can see which connectors and tools your organization relies on, which go unused, and how usage changes over time. It shows data only after you turn on tool call recording, which is off by default. The screen reports tool calls only. To review model traffic, see the AI Gateway.

Record tool calls​

After returning each tool result, the gateway queues a record of the call in Redis or Valkey. A background sender then delivers the queued records to the Enterprise Manager, which stores them for the Tool Usage screen. Turn on the queue and the token the sender authenticates with:

values.yaml
connector-gateway:
  enterpriseConfig:
    outbox:
      enabled: true
  meteringTokenProjection:
    enabled: true

The sender reuses the gateway's Enterprise Manager connection from enterpriseConfig.directory, and the queue uses the Redis or Valkey instance the gateway already needs. The platform chart adds the gateway's ServiceAccount to the Enterprise Manager's metering allowlist, and the Enterprise Manager validates the token against the clusterOidcIssuer you set in Connect the gateway to the Enterprise Manager.

Queued records survive gateway restarts only if your Redis or Valkey instance does, so use a Redis or Valkey deployment with persistence and replication when you rely on these numbers. The chart refuses to render when outbox.enabled is true and meteringTokenProjection.enabled is false.

Read the screen​

Choose Last 24h (the default), Last 7d, or Last 30d to set the period for everything on the screen except the Tool calls trend chart, which always covers the Last 3 months. The period applies to:

  • The Tool calls tile: calls in the period.
  • The Active connectors tile: connectors with at least one call in the period.
  • The Top connector tile: the connector with the most calls, and its count.
  • The By connector tab, with Connector, Calls, and Share columns.
  • The By tool tab, with Tool, Connector, Calls, and Share columns.

Each tab lists up to 100 rows, busiest first, and Share is each row's percentage of the calls in that tab. The tiles are computed from the rows on the By connector tab. When more than 100 connectors or tools have calls in the period, the tiles and Share cover only the listed rows, so Tool calls and Active connectors undercount the organization-wide totals.

Answer common questions​

Which connectors and tools get the most use?​

Open the By connector tab to rank connectors by call volume. Open By tool to see the individual tools behind that volume, with the connector that serves each one.

Which connectors might be unused?​

Set the period to Last 30d and compare the By connector tab with the connectors list under Connectors. A connector missing from the tab is a candidate for review, not proof of zero use: it might have calls but fall outside the 100 busiest connectors, or have calls from before you turned on recording. Before you delete a connector, confirm it has no calls in a complete record, such as audit logs collected over the same period.

If a connector you expect to be busy has no calls, check that the right groups have access to it. See Grant and revoke connector access.

Is adoption growing?​

The Tool calls trend chart plots calls across all connectors for the last three months. Compare the line before and after you add a connector or roll out gateway clients to a new group.

Who is calling a connector?​

The Tool Usage screen aggregates calls and doesn't break them down by user, and connector names in the tables aren't links. For per-user and per-call detail, open the connector from the Connectors list and select its Activity tab. See Review activity.

Users see a summary of their own calls on the Usage tab under Gateways > Connectors. See Support users' connector access.

Next steps​

Troubleshooting​

The screen shows "No tool calls in this window"

Check that tool call recording is on, as described in Record tool calls. The gateway records only calls made after you turn it on.

If recording is on, check the gateway's logs for errors delivering records to the Enterprise Manager:

kubectl logs deployment/stacklok-enterprise-connector-gateway -n stacklok-system

An Unauthenticated error means the Enterprise Manager can't validate the gateway's token. Check that enterprise-manager.grpc.callerAuth.clusterOidcIssuer matches the issuer your cluster reports.

A connector that users call doesn't appear

The screen lists only connectors with recorded calls in the selected period, up to the 100 busiest. If users can't call the connector at all, see Troubleshooting on the connectors page.