File size: 4,889 Bytes
c44600e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | # Local development guide
This guide provides instructions for setting up and using local development
features for Gemini CLI.
## Tracing
Gemini CLI uses OpenTelemetry (OTel) to record traces that help you debug agent
behavior. Traces instrument key events like model calls, tool scheduler
operations, and tool calls.
Traces provide deep visibility into agent behavior and help you debug complex
issues. They are captured automatically when you enable telemetry.
### View traces
You can view traces using Genkit Developer UI, Jaeger, or Google Cloud.
#### Use Genkit
Genkit provides a web-based UI for viewing traces and other telemetry data.
1. **Start the Genkit telemetry server:**
Run the following command to start the Genkit server:
```bash
npm run telemetry -- --target=genkit
```
The script will output the URL for the Genkit Developer UI. For example:
`Genkit Developer UI: http://localhost:4000`
2. **Run Gemini CLI:**
In a separate terminal, run your Gemini CLI command:
```bash
gemini
```
3. **View the traces:**
Open the Genkit Developer UI URL in your browser and navigate to the
**Traces** tab to view the traces.
#### Use Jaeger
You can view traces in the Jaeger UI for local development.
1. **Start the telemetry collector:**
Run the following command in your terminal to download and start Jaeger and
an OTel collector:
```bash
npm run telemetry -- --target=local
```
This command configures your workspace for local telemetry and provides a
link to the Jaeger UI (usually `http://localhost:16686`).
- **Collector logs:** `~/.gemini/tmp/<projectHash>/otel/collector.log`
2. **Run Gemini CLI:**
In a separate terminal, run your Gemini CLI command:
```bash
gemini
```
3. **View the traces:**
After running your command, open the Jaeger UI link in your browser to view
the traces.
#### Use Google Cloud
You can use an OpenTelemetry collector to forward telemetry data to Google Cloud
Trace for custom processing or routing.
<!-- prettier-ignore -->
> [!WARNING]
> Ensure you complete the
> [Google Cloud telemetry prerequisites](./cli/telemetry.md#prerequisites)
> (Project ID, authentication, IAM roles, and APIs) before using this method.
1. **Configure `.gemini/settings.json`:**
```json
{
"telemetry": {
"enabled": true,
"target": "gcp",
"useCollector": true
}
}
```
2. **Start the telemetry collector:**
Run the following command to start a local OTel collector that forwards to
Google Cloud:
```bash
npm run telemetry -- --target=gcp
```
The script outputs links to view traces, metrics, and logs in the Google
Cloud Console.
- **Collector logs:** `~/.gemini/tmp/<projectHash>/otel/collector-gcp.log`
3. **Run Gemini CLI:**
In a separate terminal, run your Gemini CLI command:
```bash
gemini
```
4. **View logs, metrics, and traces:**
After sending prompts, view your data in the Google Cloud Console. See the
[telemetry documentation](./cli/telemetry.md#view-google-cloud-telemetry)
for links to Logs, Metrics, and Trace explorers.
For more detailed information on telemetry, see the
[telemetry documentation](./cli/telemetry.md).
### Instrument code with traces
You can add traces to your own code for more detailed instrumentation.
Adding traces helps you debug and understand the flow of execution. Use the
`runInDevTraceSpan` function to wrap any section of code in a trace span.
Here is a basic example:
```typescript
import { runInDevTraceSpan } from '@google/gemini-cli-core';
import { GeminiCliOperation } from '@google/gemini-cli-core/lib/telemetry/constants.js';
await runInDevTraceSpan(
{
operation: GeminiCliOperation.ToolCall,
attributes: {
[GEN_AI_AGENT_NAME]: 'gemini-cli',
},
},
async ({ metadata }) => {
// metadata allows you to record the input and output of the
// operation as well as other attributes.
metadata.input = { key: 'value' };
// Set custom attributes.
metadata.attributes['custom.attribute'] = 'custom.value';
// Your code to be traced goes here.
try {
const output = await somethingRisky();
metadata.output = output;
return output;
} catch (e) {
metadata.error = e;
throw e;
}
},
);
```
In this example:
- `operation`: The operation type of the span, represented by the
`GeminiCliOperation` enum.
- `metadata.input`: (Optional) An object containing the input data for the
traced operation.
- `metadata.output`: (Optional) An object containing the output data from the
traced operation.
- `metadata.attributes`: (Optional) A record of custom attributes to add to the
span.
- `metadata.error`: (Optional) An error object to record if the operation fails.
|