{"id":19183884,"url":"https://github.com/evidentlyai/tracely","last_synced_at":"2025-05-07T23:49:37.814Z","repository":{"id":249728250,"uuid":"832308832","full_name":"evidentlyai/tracely","owner":"evidentlyai","description":"LLM application tracing based on OpenTelemetry","archived":false,"fork":false,"pushed_at":"2025-02-21T13:23:26.000Z","size":54,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-07T23:49:29.001Z","etag":null,"topics":["lllmops","model-monitoring","observability","open-telemetry","tracing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evidentlyai.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}},"created_at":"2024-07-22T18:51:54.000Z","updated_at":"2025-02-21T13:18:54.000Z","dependencies_parsed_at":"2024-07-23T01:52:42.353Z","dependency_job_id":"3e803bec-b668-47f3-9bfe-5055688d9745","html_url":"https://github.com/evidentlyai/tracely","commit_stats":null,"previous_names":["evidentlyai/tracely"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentlyai%2Ftracely","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentlyai%2Ftracely/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentlyai%2Ftracely/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evidentlyai%2Ftracely/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evidentlyai","download_url":"https://codeload.github.com/evidentlyai/tracely/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252973626,"owners_count":21834105,"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","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":["lllmops","model-monitoring","observability","open-telemetry","tracing"],"created_at":"2024-11-09T11:05:26.442Z","updated_at":"2025-05-07T23:49:37.795Z","avatar_url":"https://github.com/evidentlyai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tracely\n\nTracely is a tool designed for tracing and monitoring AI model interactions, enabling you to gain real-time insights into your models' performance. This repository offers a straightforward interface for integrating tracing into your Python applications.\n\n## Getting Started\n\n### Prerequisites\n\n- Python 3.x\n- An account on [Evidently Cloud](https://app.evidently.cloud/)\n- API Key from your Evidently account\n\n### Installation\n\nTracely is available as a PyPI package. To install it using pip package manager, run:\n```bash\npip install tracely\n```\n\n\n### Usage\n\n#### Init\n\nTo send your traces to Evidently you need to initialize tracely:\n\n```python\nfrom tracely import init_tracing\n\ninit_tracing(\n    address=\"https://app.evidently.cloud\",              # Trace Collector Address\n    api_key=\"\",                                         # API Key from Evidently Cloud\n    project_id=\"a1d08c46-0624-49e3-a9f5-11a13b4a2aa5\",  # Project ID from Evidently Cloud\n    export_name=\"tracing-dataset\",\n)\n```\n\nAll parameters can be set using environment varialbes:\n\n- `EVIDENTLY_TRACE_COLLECTOR` - trace collector address (default to https://app.evidently.cloud)\n- `EVIDENTLY_TRACE_COLLECTOR_API_KEY` - API Key to access Evidently Cloud for creating dataset and uploading traces\n- `EVIDENTLY_TRACE_COLLECTOR_EXPORT_NAME` - Export name in Evidently Cloud\n- `EVIDENTLY_TRACE_COLLECTOR_PROJECT_ID` - Project ID from Evidently Cloud to create Export dataset in\n\n#### Decorator\nOnce Tracely is initialized, you can decorate your functions with `trace_event` to start collecting traces for a specific function:\n\n```python\nfrom tracely import init_tracing\nfrom tracely import trace_event\n\n\ninit_tracing()\n\n@trace_event()\ndef process_request(question: str, session_id: str):\n    # do work\n    return \"work done\"\n```\nThe `trace_event` decorator accepts several arguments:\n\n- `span_name` - the name of the span to send in the event (defaults to the function name)\n- `track_args` - a list of function arguments to include in the event (defaults to `None`, indicating that all arguments should be included)\n- `ingore_args` - a list of function arguments to exclude (defaults to `None`, meaning no arguments are ignored)\n- `track_output` - indicates whether the event should track the function's return value (defaults to `True`)\n- `parse_output` - indicates whether the result should be parsed (e.g., dict, list, and tuple types would be split into separate fields; defaults to `True`)\n\n#### Context Manager\n\nIf you need to create a trace event without using a decorator (e.g., for a specific piece of code), you can do so with the context manager:\n\n```python\nimport uuid\n\nfrom tracely import init_tracing\nfrom tracely import create_trace_event\n\n\ninit_tracing()\n\nsession_id = str(uuid.uuid4())\n\nwith create_trace_event(\"external_span\", session_id=session_id) as event:\n    event.set_attribute(\"my-attribute\", \"value\")\n    # do work\n    event.set_result({\"data\": \"data\"})\n```\n\nThe `create_trace_event` function accepts the following arguments:\n\n- `name` - the name of the event to label it\n- `parse_output` - indicates whether the result (if set) should be parsed (dict, list and tuple types would be split in separate fields), default to `True`\n- `**params` - key-value style parameters to set as attributes\n\nThe `event` object has the following methods:\n\n- `set_attribute` - set a custom attribute for the event\n- `set_result` - set a result for the event (only one result can be set per event)\n\n\n## Extending events with additional attributes\n\nIf you want to add a new attribute to active event span, you can use `get_current_span()` to get access to current span:\n\n```python\nimport uuid\n\nfrom tracely import init_tracing\nfrom tracely import create_trace_event\nfrom tracely import get_current_span\n\ninit_tracing()\n\nsession_id = str(uuid.uuid4())\n\nwith create_trace_event(\"external_span\", session_id=session_id):\n    span = get_current_span()\n    span.set_attribute(\"my-attribute\", \"value\")\n    # do work\n    span.set_result({\"data\": \"data\"})\n\n```\n\nObject from `tracely.get_current_span()` have 2 methods:\n\n- `set_attribute` - add new attribute to active span\n- `set_result` - set a result field to an active span (have no effect in decorated functions with return values)\n\n## Connecting event to existing trace\nSometimes events are distributed across different systems, but you want to connect them into single trace.\n\nTo do so, you can use `tracely.bind_to_trace`:\n\n```python\nimport tracely\n\n@tracely.trace_event()\ndef process_request(question: str, session_id: str):\n    # do work\n    return \"work done\"\n\n# trace id is unique 128-bit integer representing single trace\ntrace_id = 1234\n\nwith tracely.bind_to_trace(trace_id):\n    process_request(...)\n```\n\nIn this case instead of creating new TraceID for events this events will be bound to trace with given TraceID.\n\n**Warning**: in this case TraceID management is in user responsibility, if user provide duplicated TraceID all events would be bound to same trace.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevidentlyai%2Ftracely","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevidentlyai%2Ftracely","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevidentlyai%2Ftracely/lists"}