{"id":32368891,"url":"https://github.com/stackgenhq/tracenet","last_synced_at":"2025-11-11T18:07:01.986Z","repository":{"id":309647210,"uuid":"1028672036","full_name":"stackgenhq/Tracenet","owner":"stackgenhq","description":"A universal tracing middleware for agent applications with support for multiple tracing backends. This package provides automatic tracing setup - just import and go!","archived":false,"fork":false,"pushed_at":"2025-08-16T20:05:29.000Z","size":118,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-16T21:21:45.084Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/stackgenhq.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-07-29T22:17:42.000Z","updated_at":"2025-08-29T17:44:19.000Z","dependencies_parsed_at":"2025-08-13T03:47:49.206Z","dependency_job_id":"00cf2380-ff76-47df-b177-c83b50189405","html_url":"https://github.com/stackgenhq/Tracenet","commit_stats":null,"previous_names":["stackgenhq/tracenet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stackgenhq/Tracenet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackgenhq%2FTracenet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackgenhq%2FTracenet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackgenhq%2FTracenet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackgenhq%2FTracenet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackgenhq","download_url":"https://codeload.github.com/stackgenhq/Tracenet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackgenhq%2FTracenet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280856747,"owners_count":26403188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-24T02:00:06.418Z","response_time":73,"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":"2025-10-24T19:35:19.954Z","updated_at":"2025-10-24T19:35:24.990Z","avatar_url":"https://github.com/stackgenhq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eTracenet\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI version](https://badge.fury.io/py/tracenet.svg)](https://badge.fury.io/py/tracenet)\n[![npm version](https://badge.fury.io/js/%40stackgen-ai%2Ftracenet.svg)](https://www.npmjs.com/package/@stackgen-ai/tracenet)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python Versions](https://img.shields.io/pypi/pyversions/tracenet.svg)](https://pypi.org/project/tracenet/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)\n\n**Universal tracing middleware for LLM-powered applications with seamless integration and powerful observability.**\n\n[Quick Start](#-quick-start) •\n[Installation](#-installation) •\n[Features](#-features) •\n[Examples](#-examples) •\n[Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## 🌟 Overview\n\nTracenet is a specialized tracing middleware designed for Large Language Model (LLM) applications and AI agents. It provides comprehensive observability for applications using LLMs, autonomous AI agents, and other generative AI components.\n\n### Why Tracenet?\n\nModern LLM applications face several critical challenges:\n- **Complexity**: LLM interactions are complex, involving multiple steps, retries, and chain-of-thought processes\n- **Observability Gap**: Traditional APM tools don't understand LLM-specific concepts like prompt engineering, token usage, or completion quality\n- **Integration Overhead**: Manually instrumenting each LLM interaction is time-consuming and error-prone\n\nTracenet solves these challenges by providing:\n- **Zero-Config Auto-Instrumentation**: Automatically captures LLM interactions, tokens, latency, and costs\n- **AI-Native Design**: Purpose-built for LLM applications with deep understanding of AI patterns\n- **Universal Integration**: Works with any LLM framework or provider while maintaining consistent observability\n\nUnlike general-purpose tracing tools, Tracenet is specifically designed for LLM applications, offering:\n- Native understanding of LLM concepts (prompts, completions, tokens)\n- Automatic framework detection for popular LLM libraries\n- Built-in support for common AI patterns and architectures\n\n### Key Benefits\n\n- 🚀 **Zero-Config Setup**: Just import and go - automatic framework detection and configuration\n- 🔄 **Language Agnostic**: First-class support for both Python and TypeScript\n- 🎯 **AI-First Design**: Built specifically for tracing AI/ML applications\n- 📊 **Rich Observability**: Detailed tracing for both automatic and manual instrumentation\n- 🔌 **Extensible**: Plugin architecture for custom tracing backends\n\n### Architecture\n\nThe following diagram illustrates Tracenet's architecture and integration points:\n\n```mermaid\ngraph TD\n    A[Your Application] --\u003e B[Tracenet Middleware]\n    B --\u003e C{Framework Detection}\n    \n    C --\u003e|Auto-Detect| D[Native Integrations]\n    D --\u003e D1[OpenAI SDK]\n    D --\u003e D2[LangChain]\n    D --\u003e D3[CrewAI]\n    D --\u003e D4[Google ADK]\n    D --\u003e D5[Other Frameworks...]\n    \n    C --\u003e|Manual| E[Manual Instrumentation]\n    E --\u003e E1[Decorators]\n    E --\u003e E2[Context Managers]\n    E --\u003e E3[Direct API]\n    \n    B --\u003e F{Tracing Backend}\n    F --\u003e|Default| G[Langfuse]\n    F --\u003e|Extensible| H[Custom Backends]\n    \n    style A fill:#f9f,stroke:#333,stroke-width:2px\n    style B fill:#bbf,stroke:#333,stroke-width:2px\n    style C fill:#dfd,stroke:#333,stroke-width:2px\n    style F fill:#dfd,stroke:#333,stroke-width:2px\n    style G fill:#fdd,stroke:#333,stroke-width:2px\n    style H fill:#fdd,stroke:#333,stroke-width:2px\n```\n\n## 🚀 Quick Start\n\n### Python\n\n```python\n# Just import the package - it automatically sets up tracing\nimport tracenet\n\n# Your existing code will now be traced automatically!\nfrom openai import OpenAI\nclient = OpenAI()\n\nresponse = client.chat.completions.create(\n    model=\"gpt-3.5-turbo\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\n# The API call is automatically traced!\n```\n\n### TypeScript\n\n```typescript\n// Import the package\nimport { tracenet } from '@stackgen-ai/tracenet';\n\n// Your existing code will now be traced automatically!\nimport OpenAI from 'openai';\nconst client = new OpenAI();\n\nconst response = await client.chat.completions.create({\n    model: \"gpt-3.5-turbo\",\n    messages: [{ role: \"user\", content: \"Hello!\" }]\n});\n// The API call is automatically traced!\n```\n\n## 📦 Installation\n\n### Python\n\n```bash\npip install tracenet\n```\n\n### TypeScript/JavaScript\n\n```bash\nnpm install @stackgen-ai/tracenet\n# or\nyarn add @stackgen-ai/tracenet\n```\n\n## ✨ Features\n\n### Framework Support\n\n| Framework | Python | TypeScript | Auto-Instrumentation |\n|-----------|---------|------------|---------------------|\n| OpenAI SDK | ✅ | ✅ | ✅ |\n| Anthropic | ✅ | ✅ | ✅ |\n| LangChain | ✅ | ✅ | ✅ |\n| LlamaIndex | ✅ | - | ✅ |\n| CrewAI | ✅ | - | ✅ |\n| Google ADK | ✅ | - | ✅ |\n| Autogen | ✅ | - | ✅ |\n| Instructor | ✅ | - | ✅ |\n| Guardrails | ✅ | - | ✅ |\n| Haystack | ✅ | - | ✅ |\n| VertexAI | ✅ | - | ✅ |\n| Groq | ✅ | - | ✅ |\n| BeeAI | ✅ | - | ✅ |\n\n### Manual Instrumentation\n\nBoth Python and TypeScript support:\n\n- Function/Method Tracing\n- Context Managers/Spans\n- LLM Generation Tracking\n- Custom Attributes\n- Error Handling\n- Async Operations\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `TRACENET_TRACER` | Tracing backend to use | `langfuse` | No |\n| `TRACENET_SERVICE_NAME` | Service name for traces | `agent_service` | No |\n| `AGENT_NAME` | Agent identifier for traces | None | No |\n\n### Langfuse Backend Configuration\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `LANGFUSE_PUBLIC_KEY` | Your Langfuse public key | Yes |\n| `LANGFUSE_SECRET_KEY` | Your Langfuse secret key | Yes |\n| `LANGFUSE_HOST` | Custom Langfuse host | No |\n\n## 📚 API Reference\n\n### Python API\n\n#### Automatic Tracing\n\n```python\nimport tracenet  # Automatically sets up tracing\n```\n\n#### Manual Instrumentation\n\n```python\nfrom tracenet import trace, start_span, start_generation\n\n# Function decorator\n@trace(name=\"my_function\")\ndef my_function(arg1, arg2):\n    return arg1 + arg2\n\n# Context manager\nwith start_span(\"operation_name\", tags=[\"tag1\"]) as span:\n    result = operation()\n    span.update(output=result)\n\n# LLM Generation tracking\nwith start_generation(\"text_gen\", model=\"gpt-4\") as span:\n    response = llm.generate(\"prompt\")\n    span.update(output=response)\n```\n\n### TypeScript API\n\n#### Automatic Tracing\n\n```typescript\nimport { tracenet } from '@stackgen-ai/tracenet';  // Automatically sets up tracing\n```\n\n#### Manual Instrumentation\n\n```typescript\nimport { trace, startSpan, startGeneration } from '@stackgen-ai/tracenet';\n\n// Function decorator\n@trace({ name: \"myFunction\" })\nmyFunction(arg1: string, arg2: string): string {\n    return arg1 + arg2;\n}\n\n// Context manager\nconst span = await startSpan(\"operationName\", { tags: [\"tag1\"] });\ntry {\n    const result = await operation();\n    span.update({ output: result });\n} finally {\n    await span.end();\n}\n\n// LLM Generation tracking\nconst genSpan = await startGeneration(\"textGen\", { model: \"gpt-4\" });\ntry {\n    const response = await llm.generate(\"prompt\");\n    genSpan.update({ output: response });\n} finally {\n    await genSpan.end();\n}\n```\n\n## 🔍 Tracing Flow\n\nThe following diagram shows how Tracenet handles different types of traces:\n\n```mermaid\nsequenceDiagram\n    participant App as Your Application\n    participant TN as Tracenet\n    participant Backend as Tracing Backend\n    \n    Note over App,Backend: Automatic Framework Detection\n    App-\u003e\u003eTN: Import tracenet\n    TN-\u003e\u003eTN: Detect frameworks\n    TN-\u003e\u003eTN: Configure integrations\n    \n    Note over App,Backend: Manual Instrumentation\n    App-\u003e\u003eTN: @trace decorator\n    TN-\u003e\u003eBackend: Start span\n    App-\u003e\u003eTN: Execute function\n    TN-\u003e\u003eBackend: Update span\n    TN-\u003e\u003eBackend: End span\n    \n    Note over App,Backend: Context Managers\n    App-\u003e\u003eTN: start_span()\n    TN-\u003e\u003eBackend: Create span\n    App-\u003e\u003eTN: Operation execution\n    App-\u003e\u003eTN: span.update()\n    TN-\u003e\u003eBackend: Update span data\n    TN-\u003e\u003eBackend: Close span\n```\n\n## 📖 Examples\n\nFor detailed examples, check out our example repositories:\n\n- [Python Examples](examples/python/)\n- [TypeScript Examples](examples/typescript/)\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/stackgenhq/tracenet\ncd tracenet\n```\n\n2. Install dependencies:\n```bash\n# Python\npip install -e \".[dev]\"\n\n# TypeScript\nnpm install\n```\n\n3. Run tests:\n```bash\n# Python\npytest\n\n# TypeScript\nnpm test\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Langfuse](https://langfuse.com) for the amazing tracing backend\n- [OpenTelemetry](https://opentelemetry.io) for inspiration on observability patterns\n- All our [contributors](https://github.com/stackgenhq/tracenet/graphs/contributors)\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with ❤️ by the Tracenet Team\n\u003c/div\u003e \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackgenhq%2Ftracenet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackgenhq%2Ftracenet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackgenhq%2Ftracenet/lists"}