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: total 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.

Share is each row's percentage of all calls in the period. Each tab lists up to 100 rows, busiest first.

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 go unused?​

The screen lists only connectors with recorded calls in the period. Set the period to Last 30d and compare the By connector tab with the connectors list under Connectors. A connector missing from the tab had no calls in 30 days. Check that the right groups have access to it, as described in Grant and revoke access, or delete it if nobody needs it.

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 Manage your connections.

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. If users can't call the connector at all, see Troubleshooting on the connectors page.