{"id":51940326,"url":"https://github.com/comet-ml/opik-springai-demo","last_synced_at":"2026-07-28T18:01:56.029Z","repository":{"id":326899233,"uuid":"1107049003","full_name":"comet-ml/opik-springai-demo","owner":"comet-ml","description":"This is a simple Spring AI Chatbot REST application that uses the OpenAI API to answer questions and OPIK server for observability and tracing.","archived":false,"fork":false,"pushed_at":"2025-12-02T11:43:20.000Z","size":25,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T10:41:41.760Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/comet-ml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-30T13:36:47.000Z","updated_at":"2026-02-19T21:16:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/comet-ml/opik-springai-demo","commit_stats":null,"previous_names":["comet-ml/opik-springai-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/comet-ml/opik-springai-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-springai-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-springai-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-springai-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-springai-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/comet-ml","download_url":"https://codeload.github.com/comet-ml/opik-springai-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-springai-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36002533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-28T18:01:55.055Z","updated_at":"2026-07-28T18:01:56.016Z","avatar_url":"https://github.com/comet-ml.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring AI Chatbot REST Application\n\nThis is a simple Spring AI Chatbot REST application that uses the OpenAI API to answer questions.\nIt demonstrates how to monitor Spring AI Chatbot using OpenTelemetry and [Opik](https://www.comet.com/docs/opik/integrations/spring-ai)\nfor observability and tracing.\n\n[Opik](https://github.com/comet-ml/opik) is the open-source LLM observability and evaluation platform, built by [Comet](https://www.comet.com). This demo traces a Spring AI chatbot into Opik through OpenTelemetry.\n\n## Table of Contents\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Running the Application](#running-the-application)\n- [Manual Testing](#manual-testing)\n- [API Endpoints](#api-endpoints)\n- [Monitoring and Observability](#monitoring-and-observability)\n- [Troubleshooting](#troubleshooting)\n\n## Prerequisites\n\nBefore running this application, ensure you have the following installed:\n\n- **Java 21** or higher\n- **Maven 3.6+** for dependency management and building\n- **OpenAI API Key** - Sign up at [OpenAI Platform](https://platform.openai.com/)\n- **OPIK API Key** - Sign up at [Comet OPIK](https://www.comet.com/opik)\n\n## Installation\n\n### 1. Clone the Repository\n```bash\ngit clone git@github.com:comet-ml/opik-springai-demo.git\ncd opik-springai-demo\n```\n\n### 2. Verify Java Installation\n```bash\njava --version\n```\nEnsure you have Java 21 or higher installed.\n\n### 3. Verify Maven Installation\n```bash\nmvn --version\n```\n\n### 4. Install Dependencies\n```bash\nmvn clean install\n```\n\n## Configuration\n\nFor additional details refer to the [OPIK documentation](https://www.comet.com/docs/opik/integrations/spring-ai).\n\n### Environment Variables\n\nThe application requires the following environment variables to be set:\n\n#### Required Variables\n\n- **OPENAI_API_KEY**: Your OpenAI API key\n- **OTEL_EXPORTER_OTLP_ENDPOINT**: OPIK OpenTelemetry endpoint\n- **OTEL_EXPORTER_OTLP_HEADERS**: Authorization headers for OPIK\n\n\n#### Setting Environment Variables: Using Cloud OPIK (Comet)\n\n**On macOS/Linux:**\n```bash\nexport OPENAI_API_KEY=\"sk-your-openai-api-key-here\"\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://www.comet.com/opik/api/v1/private/otel\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=\u003cyour-opik-api-key\u003e,Comet-Workspace=default,projectName=\u003cyour-project-name\u003e\"\n```\n\n**On Windows (Command Prompt):**\n```cmd\nset OPENAI_API_KEY=sk-your-openai-api-key-here\nset OTEL_EXPORTER_OTLP_ENDPOINT=https://www.comet.com/opik/api/v1/private/otel\nset OTEL_EXPORTER_OTLP_HEADERS=Authorization=\u003cyour-opik-api-key\u003e,Comet-Workspace=default,projectName=\u003cyour-project-name\u003e\n```\n\n**On Windows (PowerShell):**\n```powershell\n$env:OPENAI_API_KEY=\"sk-your-openai-api-key-here\"\n$env:OTEL_EXPORTER_OTLP_ENDPOINT=\"https://www.comet.com/opik/api/v1/private/otel\"\n$env:OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=\u003cyour-opik-api-key\u003e,Comet-Workspace=default,projectName=\u003cyour-project-name\u003e\"\n```\n\n#### Setting Environment Variables: Local OPIK Server\n\nIf you're running OPIK locally on port 8080, use these environment variables instead:\n\n**On macOS/Linux:**\n```bash\nexport OPENAI_API_KEY=\"sk-your-openai-api-key-here\"\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"http://localhost:5173/api/v1/private/otel\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Comet-Workspace=default,projectName=\u003cyour-project-name\u003e\"\n```\n\n**On Windows (Command Prompt):**\n```cmd\nset OPENAI_API_KEY=sk-your-openai-api-key-here\nset OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5173/api/v1/private/otel\nset OTEL_EXPORTER_OTLP_HEADERS=Comet-Workspace=default,projectName=\u003cyour-project-name\u003e\n```\n\n**On Windows (PowerShell):**\n```powershell\n$env:OPENAI_API_KEY=\"sk-your-openai-api-key-here\"\n$env:OTEL_EXPORTER_OTLP_ENDPOINT=\"http://localhost:5173/api/v1/private/otel\"\n$env:OTEL_EXPORTER_OTLP_HEADERS=\"Comet-Workspace=default,projectName=\u003cyour-project-name\u003e\"\n```\n\n**Note**: When using a local OPIK server, you don't need the `Authorization` header in `OTEL_EXPORTER_OTLP_HEADERS`.\n\n### Application Configuration\n\nThe application is configured via `src/main/resources/application.yml`:\n\n- **Server Port**: 8085 (customizable)\n- **OpenAI Model**: gpt-4o (customizable)\n- **Temperature**: 0.7 (controls response creativity)\n- **Tracing**: All requests are traced (100% sampling)\n\n## Running the Application\n\n### Method 1: Using Maven Spring Boot Plugin\n```bash\nmvn spring-boot:run\n```\n\n### Method 2: Using JAR File\n```bash\nmvn clean package\njava -jar target/spring-ai-demo-opik-0.0.1-SNAPSHOT.jar\n```\n\n### Method 3: Development Mode with Auto-reload\n```bash\nmvn spring-boot:run -Dspring-boot.run.jvmArguments=\"-Dspring.devtools.restart.enabled=true\"\n```\n\nThe application will start on **http://localhost:8085**\n\n## Manual Testing\n\n### 1. Test with curl (GET Request)\n\n**Basic question:**\n```bash\ncurl \"http://localhost:8085/api/chat/ask-me?question=What is Spring AI?\"\n```\n\n**Complex question with URL encoding:**\n```bash\ncurl --get --data-urlencode \"question=How to integrate Spring AI with OpenAI for building chatbots?\" http://localhost:8085/api/chat/ask-me\n```\n\n**Default question (if no parameter provided):**\n```bash\ncurl \"http://localhost:8085/api/chat/ask-me\"\n```\n\n### 2. Test with curl (POST Request)\n\n**Simple POST:**\n```bash\ncurl -X POST \\\n  -H \"Content-Type: text/plain\" \\\n  -d \"Explain the benefits of using OpenTelemetry for monitoring\" \\\n  http://localhost:8085/api/chat/ask\n```\n\n**POST with JSON (if needed):**\n```bash\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '\"What are the key features of Spring Boot 3.4?\"' \\\n  http://localhost:8085/api/chat/ask\n```\n\n**Enhanced POST with tags and metadata (JSON):**\n```bash\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"question\": \"What are the benefits of using Spring AI?\",\n    \"tags\": [\"spring\", \"ai\", \"tutorial\"],\n    \"metadata\": {\n      \"userId\": \"user123\",\n      \"sessionId\": \"session456\",\n      \"category\": \"educational\"\n    }\n  }' \\\n  http://localhost:8085/api/chat/ask-enhanced\n```\n\n**Enhanced POST with parameters:**\n```bash\ncurl -X POST \\\n  \"http://localhost:8085/api/chat/ask-with-params?question=What%20is%20OpenTelemetry?\u0026tags=monitoring,observability\u0026metadata=userId:123,sessionId:abc\"\n```\n\n### 3. Test with Postman\n\n#### GET Request:\n- **Method**: GET\n- **URL**: `http://localhost:8085/api/chat/ask-me`\n- **Query Parameters**:\n  - Key: `question`\n  - Value: `How to integrate Spring AI with OpenAI?`\n\n#### POST Request:\n- **Method**: POST\n- **URL**: `http://localhost:8085/api/chat/ask`\n- **Headers**: `Content-Type: text/plain`\n- **Body**: `What is the difference between Spring AI and LangChain?`\n\n#### Enhanced POST Request (JSON with tags and metadata):\n- **Method**: POST\n- **URL**: `http://localhost:8085/api/chat/ask-enhanced`\n- **Headers**: `Content-Type: application/json`\n- **Body**:\n  ```json\n  {\n    \"question\": \"What are the benefits of using Spring AI?\",\n    \"tags\": [\"spring\", \"ai\", \"tutorial\"],\n    \"metadata\": {\n      \"userId\": \"user123\",\n      \"sessionId\": \"session456\",\n      \"category\": \"educational\"\n    }\n  }\n  ```\n\n#### Enhanced POST Request (URL parameters):\n- **Method**: POST\n- **URL**: `http://localhost:8085/api/chat/ask-with-params`\n- **Query Parameters**:\n  - Key: `question`, Value: `What is OpenTelemetry?`\n  - Key: `tags`, Value: `monitoring,observability,tracing`\n  - Key: `metadata`, Value: `userId:123,sessionId:abc,environment:dev`\n\n### 4. Test with HTTPie\n```bash\nhttp GET localhost:8085/api/chat/ask-me question==\"What is machine learning?\"\n```\n\n### 5. Test with Browser\n\nOpen your browser and navigate to:\n```\nhttp://localhost:8085/api/chat/ask-me?question=Tell me about Spring Framework\n```\n\n## API Endpoints\n\n### GET /api/chat/ask-me\n- **Description**: Ask a question using query parameter\n- **Parameters**:\n  - `question` (optional): Your question (defaults to \"Tell me a joke\")\n- **Example**: `/api/chat/ask-me?question=What is AI?`\n\n### POST /api/chat/ask\n- **Description**: Ask a question using request body\n- **Content-Type**: `text/plain`\n- **Body**: Your question as plain text\n- **Example**:\n  ```\n  POST /api/chat/ask\n  Content-Type: text/plain\n\n  What is Spring AI?\n  ```\n\n### POST /api/chat/ask-enhanced\n- **Description**: Ask a question with tags and metadata for enhanced tracing\n- **Content-Type**: `application/json`\n- **Body**: JSON object with question, tags, and metadata\n- **Request Format**:\n  ```json\n  {\n    \"question\": \"Your question here\",\n    \"tags\": [\"tag1\", \"tag2\", \"tag3\"],\n    \"metadata\": {\n      \"key1\": \"value1\",\n      \"key2\": \"value2\"\n    }\n  }\n  ```\n- **Example**:\n  ```\n  POST /api/chat/ask-enhanced\n  Content-Type: application/json\n\n  {\n    \"question\": \"What are the benefits of using Spring AI?\",\n    \"tags\": [\"spring\", \"ai\", \"tutorial\"],\n    \"metadata\": {\n      \"userId\": \"user123\",\n      \"sessionId\": \"session456\",\n      \"category\": \"educational\"\n    }\n  }\n  ```\n\n### POST /api/chat/ask-with-params\n- **Description**: Ask a question with tags and metadata using URL parameters\n- **Parameters**:\n  - `question` (required): Your question\n  - `tags` (optional): Comma-separated list of tags\n  - `metadata` (optional): Key-value pairs in format `key1:value1,key2:value2`\n- **Example**: `/api/chat/ask-with-params?question=What is OpenTelemetry?\u0026tags=monitoring,observability\u0026metadata=userId:123,sessionId:abc`\n\n## Monitoring and Observability\n\n### OpenTelemetry Integration\n\nThe application automatically captures:\n- **HTTP requests** and responses\n- **OpenAI API calls** and responses\n- **Application metrics** and traces\n- **Custom spans** for business logic\n\n### Viewing Traces in OPIK\n\n1. Navigate to [Comet OPIK Dashboard](https://www.comet.com/opik)\n2. Select your workspace and project\n3. View real-time traces and metrics\n4. Analyze performance and debugging information\n\n### Health Check\n\nCheck application health:\n```bash\ncurl http://localhost:8085/actuator/health\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1. Application Won't Start\n\n**Error**: `Failed to configure a DataSource`\n- **Solution**: This shouldn't occur with this application as it doesn't use a database\n\n**Error**: `OpenAI API key not found`\n- **Solution**: Ensure `OPENAI_API_KEY` environment variable is set correctly\n\n#### 2. OpenTelemetry Issues\n\n**Error**: `Failed to export telemetry data`\n- **Solution**: Check your `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` configuration\n- **Verify**: Your OPIK API key is valid and has proper permissions\n\n#### 3. Port Already in Use\n\n**Error**: `Port 8085 is already in use`\n- **Solution**: Change the port in `application.yml`:\n  ```yml\n  server:\n    port: 8086\n  ```\n\n#### 4. OpenAI API Errors\n\n**Error**: `Rate limit exceeded`\n- **Solution**: Check your OpenAI usage limits and billing\n\n**Error**: `Invalid API key`\n- **Solution**: Verify your OpenAI API key is correct and active\n\n### Logs\n\nTo enable debug logging, add to `application.yml`:\n```yml\nlogging:\n  level:\n    com.comet.opik.examples: DEBUG\n    org.springframework.ai: DEBUG\n```\n\n### Testing Without OpenTelemetry\n\nTo run without telemetry export, set:\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"\"\n```\n\n## Additional Information\n\n### Dependencies Used\n\n- **Spring Boot 3.4.3**\n- **Spring AI 1.0.0**\n- **OpenTelemetry Instrumentation**\n- **Micrometer Tracing**\n- **Spring Boot Actuator**\n\n### Development\n\nFor development purposes, you can modify the OpenAI model and parameters in `application.yml`:\n```yml\nspring:\n  ai:\n    openai:\n      chat:\n        options:\n          model: gpt-3.5-turbo  # or gpt-4, gpt-4o-mini\n          temperature: 0.3      # Lower for more deterministic responses\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fopik-springai-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomet-ml%2Fopik-springai-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fopik-springai-demo/lists"}