# How to Configure an LLM Provider in yCrash?

yCrash provides AI-powered analysis to help you quickly identify and resolve application performance issues. AI is available from three dedicated entry points:

Deterministic AI in GCeasy (opens new window),
Deterministic AI in FastThread (opens new window), and
Dive Deeper in AI Mode button in the AI Overview section of the RCA report (opens new window).

All three entry points open an interactive AI chat session that integrates with a configured Large Language Model (LLM) provider such as Gemini or OpenAI. To activate AI, you must supply a configuration file with valid provider and model settings.

This guide is written for operations, platform, and functional teams - you do not need to be a developer to complete the setup.

# Before You Begin

Ensure the following:

Requirement	Why it matters
A Google account (for Gemini) or OpenAI account	You need access to the provider’s developer console to create an API key
A valid API key from that provider	yCrash uses this key to call the provider on your behalf
Access to the yCrash server host	You will place a small configuration file on the server
The yCrash upload directory (opens new window) path	This is where the configuration file must live (see Part C)

Without these prerequisites, the AI feature cannot be enabled.

# Quick Overview: What Happens Behind the Scenes

When configured correctly, yCrash:

Reads a file named ycbuddy-config.json at server startup
Uses your API key to connect to Google Gemini (or another supported provider)
Powers chat responses, semantic search over yCrash knowledge content, and optional file analysis in AI chat

The same API key is used for:

Chat responses (the model you choose, e.g. gemini-2.5-flash)
Semantic search / context retrieval (the embedding model, e.g. gemini-embedding-001)
File uploads in AI chat (when users attach diagnostic files)

# Setting Up Google Gemini (Recommended Walkthrough)

# Part A — Get Your Gemini API Key (Layman’s Guide)

Think of an API key as a password that lets yCrash talk to Google's AI on your behalf. You create it once in Google's portal and paste it into your yCrash configuration file.

# Step 1 - Open Google AI Studio

In a web browser, go to Google AI Studio
Sign in with your Google account (work or personal, depending on your organization's policy)

Tip for IT / procurement teams: Some organizations require a Google Cloud project with billing enabled instead of AI Studio. If your security team blocks AI Studio, ask them to provision a Gemini API key from Google Cloud Console under APIs & Services → Credentials. The key format and usage in yCrash are the same.

# Step 2 - Create an API key

In AI Studio, open Get API key (or API Keys in the left navigation)
Click Create API key
If prompted, select or create a Google Cloud project - this is a container Google uses for billing and access control
Copy the key when it is displayed

The key typically:

Starts with AIza
Is a long string of letters, numbers, and symbols
Is shown only once - store it somewhere secure (password manager, secrets vault) before closing the dialog

# Step 3 - Enable billing (if required)

Google may require billing to be enabled on the project for production API usage. Free tiers and trial credits vary by Google's current policy - check AI Studio or Cloud Console for your account's limits.

# Step 4 - Treat the key like a password

Do	Don't
Store the key in a secrets manager or restricted server directory	Email or chat the key in plain text
Restrict file permissions on `ycbuddy-config.json` (e.g. readable only by the yCrash service account)	Commit the key to Git or share it in tickets
Rotate the key if it is ever exposed	Reuse the same key across unrelated environments without tracking

# Part B - Create the yCrash Configuration File

# Step 1 - Create the file

Create a plain text file named exactly:

ycbuddy-config.json

The name is case-sensitive and mandatory. yCrash looks for this exact filename; any other name will not work.

# Step 2 - Add the Gemini settings

Paste the following JSON and replace your-gemini-api-key with the key you copied from Google:

{
  "llmProvider": "gemini",
  "llmApiKey": "your-gemini-api-key",
  "llmModelName": "gemini-2.5-flash",
  "llmEmbeddingModelName": "gemini-embedding-001"
}

1
2
3
4
5
6

# What each field means (in plain language)

Field	What it is	What to put
`llmProvider`	Which AI company yCrash should call	`"gemini"` for Google Gemini
`llmApiKey`	Your secret key from Google	The key from Part A (starts with `AIza…`)
`llmModelName`	The "brain" that writes chat answers	`"gemini-2.5-flash"` (recommended). This is the model that generates RCA explanations and answers follow-up questions.
`llmEmbeddingModelName`	A helper model for finding relevant context	`"gemini-embedding-001"`. You rarely change this. It powers semantic search over yCrash guides and conversation context — not the visible chat text itself.

Note:

If any required field is missing or empty, yCrash disables AI and logs a configuration error at startup.

# Supported Gemini chat models

yCrash recognizes these Gemini model IDs (use the exact string in llmModelName):

Model ID	Best for
`gemini-2.5-flash`	Recommended - fast, capable, good default for production RCA chat
`gemini-2.0-flash`	Fallback default in software if no model is specified
`gemini-1.5-flash`	Older flash model; still supported
`gemini-1.5-pro`	Higher capability, slower; use when analysis depth matters more than speed

If you specify an unknown model name, yCrash still runs but applies conservative token limits.

# Part C - Place the File on the yCrash Server

# Where the file must go

Place ycbuddy-config.json in the yCrash upload (opens new window) directory.

The upload directory is the folder yCrash uses to store uploaded diagnostics and server-side configuration. It is set when the JVM starts with a system property:

-DuploadDir=/path/to/your/upload/folder

Example paths:

Ask your yCrash administrator or check your server startup script / service definition for the -DuploadDir=... value if you are unsure.

Final file location:

<uploadDir>/ycbuddy-config.json

Example: if -DuploadDir=/opt/ycrash/uploads, the full path is:

/opt/ycrash/uploads/ycbuddy-config.json

# Alternate locations (for reference)

yCrash may also pick up the file from the application classpath or the server's working directory, but the upload directory is the supported location for production deployments. Always use <uploadDir>/ycbuddy-config.json unless your runbook says otherwise.

# Optional: API key via environment variable

If you prefer not to store the API key in the JSON file, you can omit llmApiKey and set an environment variable on the yCrash process instead:

LLM_API_KEY=your-gemini-api-key

All other fields (llmProvider, llmModelName, llmEmbeddingModelName) are still required in the JSON file.

# Part D - Restart yCrash and Verify

# Restart

Configuration is read when the yCrash application starts. After creating or editing ycbuddy-config.json:

Save the file
Restart the yCrash server (or redeploy the application)
Watch the server logs during startup

# What success looks like in logs

Look for messages similar to:

Found ycbuddy-config.json in uploadDir - /path/to/uploads/ycbuddy-config.json
YCBuddy configuration loaded successfully.
Streaming Gemini Client initialized successfully
Gemini embedding service initialized successfully with model: gemini-embedding-001
yCrash Buddy guide loading process started successfully

# What failure looks like

Symptom	Likely cause
AI buttons greyed out or missing	Config file not found, or required fields empty
Log: `ycbuddy-config.json file not found`	File not in upload directory, or wrong filename
Log: `LLM API key is required but not configured`	Missing `llmApiKey` and no `LLM_API_KEY` env var
Log: `Unsupported LLM provider`	Typo in `llmProvider` (must be exactly `gemini`)
Chat opens but returns auth / 403 errors	Invalid, expired, or revoked API key; or billing not enabled in Google
Log: `Gemini client not initialized`	Empty or malformed API key

# Functional verification (no log access needed)

Open a report that supports AI (GCeasy Deterministic AI or RCA Dive Deeper in AI Mode)
Confirm the AI entry point is visible and clickable
Ask a simple question (e.g. "Summarize the top GC issue in this report")
Confirm you receive a streaming response within a reasonable time (typically seconds, depending on report size)

# Optional Gemini Tuning

Most teams do not need these. Add them to ycbuddy-config.json only when directed by support or performance tuning.

{
  "llmProvider": "gemini",
  "llmApiKey": "your-gemini-api-key",
  "llmModelName": "gemini-2.5-flash",
  "llmEmbeddingModelName": "gemini-embedding-001",
  "geminiMinimizeThinking": true
}

1
2
3
4
5
6
7

Field	Default	Purpose
`geminiMinimizeThinking`	`true`	For Gemini 2.5 models, reduces internal "thinking" time so the first visible tokens arrive faster in chat

# Setting Up OpenAI (Alternative Provider)

If your organization standardizes on OpenAI instead of Gemini:

{
  "llmProvider": "openai",
  "llmApiKey": "your-openai-api-key",
  "llmModelName": "gpt-4o",
  "llmEmbeddingModelName": "text-embedding-3-small"
}