--- url: https://docs.wildedge.dev/changelog.md description: What has changed recently --- # Changelog ## November 2026 **Platform** * Added beta [Bifrost](/gateways/bifrost) gateway support over OpenTelemetry, with token use, latency, failures, retries, fallbacks, and estimated cost. * Gateway traces now include MCP tool calls from LiteLLM and Bifrost. * LiteLLM streams your app cancels are now recorded as failed. ## October 2026 **Platform** * Added beta [LLM gateway integrations](/llm-gateways) for LiteLLM and OpenRouter over OpenTelemetry. Inspect model calls, token use, latency, and reported costs without installing an SDK in your app. * Gateway fields are available in Analytics and through MCP. See the integration guide for reporting differences and beta limitations. * Added an Events gallery for browsing captured attachments, with more consistent payload details and links to individual run spans. * Agents can view, build, and edit dashboards through MCP. * Analytics charts support saved display options and thresholds, with improved bar charts and unit formatting. * Enabled model error notifications for all projects. Added Monday email summaries, notification preferences, and one-click unsubscribe. * Dashboard time windows now default to a range based on project activity. Fixed links to run traces outside the selected time range. **Python SDK [v0.3.0](https://github.com/wild-edge/wildedge-python/releases/tag/v0.3.0)** * Added local Whisper instrumentation for MLX Whisper and faster-whisper. * Added OpenAI Responses and embeddings instrumentation, plus Anthropic native streaming helpers. * Improved stream completion, cancellation, and error reporting across integrations. * Fixed missing inference events for llama.cpp chat/completion methods and Ultralytics `predict()`. * Renamed the llama.cpp integration to `llama_cpp`. `gguf` remains an alias. * Improved model metadata, accelerator detection, and SDK startup behavior. **iOS / macOS SDK [v1.1.6](https://github.com/wild-edge/wildedge-swift/releases/tag/v1.1.6)** * Added async tracing with task-local span context, preserved across `await` and inherited by child tasks. * Run, agent, and trace correlation now extends to model lifecycle events, feedback, errors, and memory warnings. * Fixed device IDs changing on every launch and made model registration thread-safe. * Added timed inference tracking, classification output helpers, and model quantization detection from filenames. * Added `ane`, `mps`, and `vulkan` accelerator values and aligned attachment upload handling with the protocol. * Expanded the car scanner example with on-device vehicle detection and brand classification, with each scan recorded as one run and trace. * **Compatibility:** custom `WildEdgeClient` conformers need updated tracing and memory-warning methods. Exhaustive accelerator switches need the new cases. Existing installs receive a new device ID once on upgrade. ## September 2026 **Platform** * Added [OAuth connections for web agents](/mcp_web), including ChatGPT and Claude. * Added SQL queries, pagination, and feedback submission through MCP. * Error rates now include failed model calls, with error-code breakdowns and links to the affected events. Failed API calls retain their duration and provider error details. * Added model error notification rules by model, version, and error code. * Improved model health comparisons, bar charts, and bounding-box overlays. * Event and attachment details are directly linkable, and attachments are available in trace views. * Refreshed project lists and mobile layouts, improved loading and network-error states, and fixed dataset list and rename issues. **Python SDK [v0.2.2](https://github.com/wild-edge/wildedge-python/releases/tag/v0.2.2)** * Failed remote calls record HTTP status, provider error codes, and elapsed time, with distinct timeout and connection errors. * Fixed Anthropic model format reporting. **Python SDK [v0.2.1](https://github.com/wild-edge/wildedge-python/releases/tag/v0.2.1)** * Documented recognized LLM providers and OpenAI-compatible endpoints, with provider documentation included in release documentation assets. ## August 2026 **Platform** * Added a guided MCP connection flow and clearer personal access token creation. * Published [coding-agent connection instructions](/mcp). * Fixed event lookup for manually added dataset items. ## July 2026 **Platform** * Introduced remote MCP access, including separate read and write permissions and tools for working with your WildEdge account. * Added dataset creation from the event explorer and dataset label overrides. * Added an Edge Impulse training integration with export checks. * Improved trace timelines and inference-call views. * Added invitation deletion and resending. **Python SDK [v0.2.0](https://github.com/wild-edge/wildedge-python/releases/tag/v0.2.0)** * Added provider-agnostic `wildedge.llm_api()` tracking for calls made with any HTTP client, including asynchronous calls and time to first token. * Expanded provider recognition for OpenAI-compatible endpoints. * Added module-level tracing APIs and a shared default client for CLI and application instrumentation. * Added end-to-end connectivity checks with `wildedge doctor --send-test-event` and stricter startup options. * Releases now include version-specific `llms.txt` and `llms-full.txt` documentation assets. **Android SDK [v1.1.0](https://github.com/wild-edge/wildedge-android/releases/tag/v1.1.0)** * Added inference attachments with configurable storage and buffered upload. * Added typed `GenerationConfig` and `ApiMeta` for generation settings and remote model response metadata. * Added queue memory and serialized-size diagnostics, plus configurable gzip compression. * Added a car scanner sample with Gemini and OpenRouter, and an on-device ExecuTorch LLM sample. ## June 2026 **Platform** * Build your own dashboards from saved charts, with configurable presentation options. * Analytics and the SQL view are now one page. New query engine, faster charts. * Added model list and per-model quality pages. * Cleaner project key management and project list. * Published a benchmarks blog post. **Python SDK [v0.1.5](https://github.com/wild-edge/wildedge-python/releases/tag/v0.1.5)** (Jun 23) * Added inference attachments. * Added macOS CPU frequency and thermal sampling. * Fixed `accelerator_actual` wiring. **iOS / macOS SDK [v1.1.0](https://github.com/wild-edge/wildedge-swift/releases/tag/v1.1.0)** (Jun 9) * Zero-code ExecuTorch LLM interceptor. No code changes in your app. * New telemetry types: `GenerationConfig` and `ApiMeta`. * Gzip compression for event batches. * Added `SDKDiagnostics` (memory, queue size, serialization time). * `app_version` is auto-detected from the host bundle. * New LLaMA.cpp and ExecuTorch example apps. * Inference duration on ONNX paths now reports ML time, not recording length. ## May 2026 **Platform** * Datasets: register Iceberg-backed datasets, curate and bulk-manage them, and download a prepared zip. * Dataset analytics with feedback correlation. * Filter events by geography (IP-based), modality, quantization, model format, error code, app version, and device model. * Clickable and multi-bar histogram selection. Infinite scroll on Events and Traces. * Inference attachments: presigned upload, access API, per-period quotas, and billing. * Self-managed companies, full project settings, team roles, and a refreshed auth flow with suspicious-login handling. * Classifier analytics now use top-1 confidence instead of average confidence. ## April 2026 **Platform** * iOS and Android SDKs in the getting started flow. * Hardware page with per-device performance, thermals, and accelerator info. * Component-based traces. * SQL assistant for querying telemetry with your own model. * Clearer ingest error messages. Model version is now optional on ingest. **Android SDK [v1.0.0](https://central.sonatype.com/artifact/dev.wildedge/wildedge-android)** (Apr 30) * First release on Maven Central. See the [setup guide](https://github.com/wild-edge/wildedge-android). **iOS / macOS SDK [v1.0.11](https://github.com/wild-edge/wildedge-swift/releases/tag/v1.0.11)** (Apr 29) * Maintenance release. **iOS / macOS SDK [v1.0.0](https://cocoapods.org/pods/WildEdge)** (Apr 27) * First release on CocoaPods. See the [setup guide](https://github.com/wild-edge/wildedge-swift). **Python SDK [v0.1.4](https://github.com/wild-edge/wildedge-python/releases/tag/v0.1.4)** (Apr 20) * Anthropic SDK integration, with an example using a Haiku model. * Moved to the production license. ## March 2026 **Python SDK [v0.1.3](https://github.com/wild-edge/wildedge-python/releases/tag/v0.1.3)** (Mar 31) * Agentic workflow monitoring. * TTFT support for remote LLM and GGUF integrations. **Python SDK [v0.1.2](https://github.com/wild-edge/wildedge-python/releases/tag/v0.1.2)** (Mar 23) * More Pythonic SDK init. * A missing DSN now turns the client into a no-op. **Python SDK [v0.1.0](https://pypi.org/project/wildedge-sdk/)** (Mar 17) * First release on PyPI. See the [setup guide](https://github.com/wild-edge/wildedge-python). --- --- url: https://docs.wildedge.dev/mcp_web.md description: >- Connect ChatGPT, Claude, or another OAuth-capable web agent to WildEdge through remote MCP. --- # Connect ChatGPT or Claude WildEdge supports OAuth authentication for remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) clients. This lets web agents such as ChatGPT and Claude connect to your WildEdge account through a browser sign-in. You do not need to create or copy a token. Use this MCP server URL in your agent: ```text https://app.wildedge.dev/mcp ``` During setup, the agent redirects you to WildEdge. You sign in, choose **Read** or **Read + Write**, and authorize the connection. WildEdge then issues and manages the OAuth credentials for that agent. ::: tip Using Codex, Claude Code, or Gemini CLI? For Codex CLI, Claude Code, or Gemini CLI, see [Connect Codex, Claude Code, or Gemini CLI](/mcp). ::: ## Connect ChatGPT ### 1. Open Plugins In ChatGPT, select **Plugins** in the left sidebar. On the Plugins page, select the **+** button. ![ChatGPT setup: add a plugin from the Plugins page](./assets/2_chat_gpt_plugin_add.png) ### 2. Add the WildEdge MCP server Fill in the **New Plugin** form: * **Name:** `WildEdge` (or another name you will recognize) * **Connection:** **Server URL** * **Server URL:** `https://app.wildedge.dev/mcp` * **Authentication:** **OAuth** You can leave the icon, description, and advanced OAuth settings unchanged. Review ChatGPT's custom MCP server warning, acknowledge it if you trust this WildEdge endpoint, and select **Create**. ::: warning Use the exact server URL Enter `https://app.wildedge.dev/mcp`. Do not enter the documentation URL or the WildEdge dashboard URL. ::: ### 3. Continue to WildEdge ChatGPT opens a connection screen. Select **Sign in with WildEdge** to continue in your browser. Then complete the [shared WildEdge authorization flow](#authorize-in-wildedge). ## Connect Claude ### 1. Open Customize In Claude, select **Customize** in the left sidebar. ### 2. Add a custom connector Open **Connectors**, then select **Add**. ![Claude setup: Connectors page with the Add button highlighted](./assets/2_claude_connectors_add.png) From the menu, select **Add custom connector**. ![Claude setup: Add custom connector in the Add menu](./assets/2_claude_connectors_custom.png) ### 3. Enter the WildEdge server URL Name the connector `WildEdge`, enter `https://app.wildedge.dev/mcp` as the connector URL, and select **Continue**. ::: warning Use the exact server URL Enter `https://app.wildedge.dev/mcp`. Do not enter the documentation URL or the WildEdge dashboard URL. ::: ### 4. Confirm the detected authentication settings Claude asks follow-up questions about authentication. WildEdge supports the settings Claude detects: * **Authentication:** **Always required** * **OAuth client:** **No client ID** (automatic registration) Keep these detected settings, leave **Advanced** unchanged, and finish adding the connector. ### 5. Connect Claude On the new WildEdge connector, select **Connect** to start the OAuth flow. Then complete the [shared WildEdge authorization flow](#authorize-in-wildedge). For a Team or Enterprise organization, an owner may need to add WildEdge under **Organization connectors** before individual members can connect it. See [Anthropic's custom connector guide](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp) for plan and organization details. ## Authorize in WildEdge The following steps are the same whether you connect ChatGPT, Claude, or another OAuth-capable web agent. 1. If you are not already signed in to WildEdge, sign in when prompted. 2. On the authorization screen, choose the least privilege the agent needs: * **Read** lets the agent inspect the companies, projects, events, traces, dashboards, datasets, and integrations available to your WildEdge account. * **Read + Write** also lets the agent create or update data through the write tools exposed by WildEdge MCP. 3. Select **Authorize**. WildEdge returns you to the agent, which completes the connection. Your WildEdge password and session stay with WildEdge. The agent receives OAuth credentials only after you approve the connection. Start with **Read** unless you intend to ask the agent to make changes. You can change the connection's permissions later in WildEdge. ## Finish setup in your agent ### Claude: set tool permissions After authorizing the connection, open the WildEdge connector to control how Claude may use each MCP tool. Claude can allow a tool automatically, require your approval before using it, or disable it. You can set a default for a group and override individual tools. ![Claude setup: granular permissions for individual WildEdge MCP tools](./assets/6_claude_permissions.png) Claude's tool permissions are an independent, additional control layer. They do not expand the **Read** or **Read + Write** access granted in WildEdge. A tool works only when both WildEdge and Claude allow it. ### Try the connection Start a chat with the WildEdge plugin or connector available and ask a read-only question first: > List the WildEdge companies available to me, including my role in each company. Do not make any changes. The agent discovers the tools exposed by WildEdge automatically. Its access remains limited by both your WildEdge account permissions and the permission level you approved for this OAuth connection. ## Manage or revoke access To review a connected web agent: 1. Sign in to [WildEdge](https://app.wildedge.dev/). 2. Open your profile and find **MCP access**. 3. Select the **OAuth connections** tab. 4. Select a connection to change it between **Read** and **Read + Write**, or choose **Disconnect** to revoke it. ![WildEdge MCP access page with the OAuth connections tab selected](./assets/6_wildedge_oauth_tokens.png) Permission changes take effect immediately. Disconnecting revokes the connection and requires that agent to complete the sign-in flow again before it can use WildEdge. ## Troubleshooting * **The agent does not start the sign-in flow:** confirm the server URL is exactly `https://app.wildedge.dev/mcp` and authentication is set to OAuth. * **The agent cannot see a company or project:** MCP access follows the permissions of the WildEdge user who authorized the connection. * **A write action is unavailable:** change the connection to **Read + Write** under **MCP access → OAuth connections**, then retry. * **A connection is unfamiliar or no longer needed:** disconnect it immediately from the **OAuth connections** tab. ## Next * [Try your first investigation](/connect-agent#try-your-first-investigation) with a read-only prompt. * [Investigate events and traces](/investigate) step by step. --- --- url: https://docs.wildedge.dev/mcp.md description: >- Connect Claude Code, Codex, or Gemini CLI to create projects, investigate telemetry, and manage your team. --- # Connect Codex, Claude Code, or Gemini CLI WildEdge's remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server lets a local AI agent work with your WildEdge account. You can ask the agent to create a project, inspect recent inference events, follow a trace, or investigate a failure without copying data between your browser and terminal. The remote endpoint is: ```text https://app.wildedge.dev/mcp ``` You do not need to install or run an MCP server locally. ::: tip Using ChatGPT or Claude? Follow [Connect ChatGPT or Claude](/mcp_web) to sign in with OAuth. ::: ## Connect your agent Create a personal MCP token, then add the WildEdge remote server to your local coding agent. ### Create an MCP token 1. Sign in to [WildEdge](https://app.wildedge.dev/). 2. Open your profile and find **MCP access tokens**. ![MCP token table: no access tokens have been created](./assets/mcp_token_table_empty.png) 3. Select **Create token** and give the token a name that identifies the client, such as `Codex on MacBook`. 4. Choose the least privilege the client needs: * **Read** can inspect the companies, projects, events, traces, dashboards, datasets, and integrations available to your account. * **Read + Write** can also create projects and project keys, and perform the other write actions exposed by the MCP server. ![MCP token dialog: creating a read and write token](./assets/mcp_token_creation_readwrite.png) 5. Create the token and copy it immediately. The full token is shown only once. ![MCP token screenshot: the one-time token display](./assets/mcp_token_created.png) Store the token in an environment variable for the commands below: ```sh export WILDEDGE_MCP_TOKEN="we_mcp_..." ``` ::: warning Protect the token An MCP token acts with your WildEdge account's access. Do not commit it to source control or paste it into prompts. Use a separate token for each client so you can revoke one without interrupting the others. Delete a token from your profile as soon as it is no longer needed. ::: #### Change permissions or revoke a token Select a token in the table to change it between **Read** and **Read + Write**, or to delete it. WildEdge shows the effect of a permission change before you save it. Deleting a token immediately disconnects clients that use it. ![MCP token dialog: changing a token from read and write access to read-only access](./assets/mcp_token_edit_change.png) ### Add WildEdge MCP to your agent Choose the client you use. The name `wildedge` in these examples is local to the client and can be changed. #### Codex CLI ```sh codex mcp add wildedge \ --url https://app.wildedge.dev/mcp \ --bearer-token-env-var WILDEDGE_MCP_TOKEN codex mcp list ``` Codex stores the name of the environment variable, not the token itself. Make sure `WILDEDGE_MCP_TOKEN` is available whenever you start Codex. #### Claude Code ```sh claude mcp add-json --scope user wildedge \ '{"type":"http","url":"https://app.wildedge.dev/mcp","headers":{"Authorization":"Bearer ${WILDEDGE_MCP_TOKEN}"}}' claude mcp get wildedge ``` Claude Code expands `${WILDEDGE_MCP_TOKEN}` from the environment when it connects. Inside Claude Code, run `/mcp` to inspect the connection and authentication status. #### Gemini CLI ```sh gemini mcp add --scope user --transport http \ --header "Authorization: Bearer ${WILDEDGE_MCP_TOKEN}" \ wildedge https://app.wildedge.dev/mcp ``` Restart Gemini CLI, then run `/mcp list` to check the connection. ::: warning Gemini stores the expanded header The shell expands `WILDEDGE_MCP_TOKEN` before Gemini saves this server, so the bearer token is stored in your user-level Gemini settings. Protect `~/.gemini/settings.json`, never commit it, and delete or rotate the WildEdge token if that file is exposed. ::: ## Example workflows After the connection works, your agent discovers the tools available to your account. You can work with WildEdge in natural language while the MCP server enforces your user access and token permissions. Start by establishing the account context without making changes: > List the WildEdge companies available to me, including my role in each company. Then list the projects in the Acme company. Do not make any changes. Use the company and project names returned by the agent in the workflows below. ### Create a project in a company **Requires:** an MCP token with **Read + Write** and membership in the company. Ask the agent to create a project and return its initial `WILDEDGE_DSN`: > Create a WildEdge project named “Checkout classifier” in the Acme company. Show me the returned `WILDEDGE_DSN` and explain where to put it in my SDK configuration. Review the company and project name before approving the write tool. The returned `WILDEDGE_DSN` is an SDK credential: store it in an environment variable or secret manager and do not commit it to source control. You can also ask the agent to create an additional project key for an existing project when another environment or device fleet needs a separate DSN. ### Investigate recent inference events **Requires:** an MCP token with **Read** access. The agent can inspect a bounded page of recent events from the last 1 to 168 hours. A focused prompt gives it enough context to retrieve useful data: > For the Checkout classifier project in the Acme company, inspect up to 25 events from the last 24 hours. Highlight failures and unusually long durations. Do not make any changes. For a suspicious event, ask for its normalized telemetry and the surrounding run trace: > Open event `` from the previous result. Explain the inputs, outputs, errors, and timing that are available. If it belongs to a run, follow the run trace and summarize where the problem started. The agent reasons over the events returned by WildEdge. It does not automatically analyze every event in the company. Specify the company, project, time window, and event type when you want a narrower investigation. ### Invite a colleague **Requires:** an MCP token with **Read + Write** and company administrator access. First, review the current team: > List the current members of the Acme company and their roles. Do not invite or remove anyone. Then request an invitation with an explicit role: > Invite `alex@example.com` to the Acme company with the `VIEWER` role. Confirm the company, email address, and role with me before sending the invitation. Supported roles are `ADMIN`, `USER`, and `VIEWER`. Inviting a colleague sends an external invitation, so review the email address and requested role before approving the tool call. ### Supported tools The supported tools are dynamic and may change. Your agent discovers the tools available through the WildEdge MCP server automatically. The examples below highlight some basic tools for reference and are not a complete list. | Tool | Description | | --- | --- | | `get_current_user` | Get the authenticated token owner. | | `list_companies` | List available companies and roles. | | `invite_company_user` | Invite a colleague. | | `get_company_usage` | Get plan, retention, and quota usage. | | `list_apps` | List active projects. | | `create_app` | Create a project and return its initial `WILDEDGE_DSN`. | | `app_details` | Get project metadata. | | `list_dashboards` | List dashboard metadata. | Use a **Read** token for investigation-only sessions. Grant **Read + Write** only to clients that need to create projects, keys, or invitations. ## Troubleshooting * **Unauthorized or disconnected:** confirm that `WILDEDGE_MCP_TOKEN` is set in the same shell that starts the agent, and that the token has not expired or been deleted. * **A write action is unavailable:** edit the token in your WildEdge profile and grant **Read + Write**, or create a separate write-enabled token. * **The agent cannot see a company or project:** MCP access follows the permissions of the WildEdge user who created the token. * **A token may have been compromised:** delete it immediately in **MCP access tokens**, create a replacement, and update only the affected client. ## Next * [Try your first investigation](/connect-agent#try-your-first-investigation) with a read-only prompt. * [Investigate events and traces](/investigate) step by step. --- --- url: https://docs.wildedge.dev/connect-agent.md description: >- Connect Codex, Claude Code, Gemini CLI, ChatGPT, or Claude to WildEdge through the remote MCP server, and point it at these docs. --- # Connect your AI agent Connect your agent to WildEdge through the remote MCP server to inspect events, follow traces, and investigate failures. Choose the client you use. ## Choose your agent | Agent | Connection | Setup | | --- | --- | --- | | Codex CLI, Claude Code, Gemini CLI | Personal MCP token | [Connect with a token](/mcp) | | ChatGPT, Claude, or another OAuth-capable web agent | Browser sign-in with OAuth | [Connect with OAuth](/mcp_web) | Both use the remote endpoint below. No local MCP server is required. ```text https://app.wildedge.dev/mcp ``` Start with **Read** access for investigation. Use **Read + Write** when you want your agent to create projects or perform other write actions. ## Try your first investigation After connecting, ask: > List the WildEdge companies and projects available to me. Do not make any changes. Then use the returned company and project names: > For project `PROJECT` in company `COMPANY`, inspect up to 25 events from the last 24 hours. Summarize failures, slow calls, and the telemetry available to explain them. Do not make any changes. [Continue to investigate events and traces →](/investigate) ## Give your agent these docs The docs are published in Markdown for agents: * [`/llms.txt`](https://docs.wildedge.dev/llms.txt): an index of every page with a one-line summary. * [`/llms-full.txt`](https://docs.wildedge.dev/llms-full.txt): all pages in one file. * Any page as Markdown: add `.md` to its URL, for example [`/telemetry.md`](https://docs.wildedge.dev/telemetry.md). To have your agent instrument your app, ask: > Read https://docs.wildedge.dev/llms.txt, then add WildEdge to this project. Use the setup that matches how we run models. ::: tip Connecting before instrumentation? You can connect your agent first. A connection with write access can help create a project and project key. Follow your client's setup guide, then [choose your instrumentation setup](/). ::: ## Next * [Investigate events and traces](/investigate) with your agent. * [How WildEdge works](/concepts) explains the events, runs, charts, and datasets your agent can work with. --- --- url: https://docs.wildedge.dev/concepts.md description: >- The building blocks of WildEdge, from projects, keys, events, runs, and attachments to SQL charts, dashboards, datasets, and training export. --- # How WildEdge works Your app or LLM gateway sends **events** to a **project**. You investigate them as events and runs, query them with **SQL**, chart them on **dashboards**, and turn the useful ones into **datasets** you can export for training. ## Companies and projects A **company** is your organization in WildEdge. It holds your team and billing. A **project** holds the telemetry for one application or environment, for example `ios-app` or `support-bot-staging`. Events, runs, datasets, charts, dashboards, and training integrations all belong to a project. Most teams use one project per application and environment. ## Keys and tokens Three kinds of credential do three different jobs. None of them can do another's job. | Credential | What it does | Where you get it | | --- | --- | --- | | **DSN** (project key) | Sends telemetry into one project. Cannot read data. | Project **API Keys**, then **Reveal DSN** | | **MCP token** or **OAuth sign-in** | Lets your AI agent read data, and with write access create projects, charts, and dashboards | Your profile, or the agent's sign-in flow. See [Connect your AI agent](/connect-agent). | | **Training provider API key** | Lets WildEdge upload datasets to an external training service | The provider, for example Edge Impulse | A DSN looks like `https://@ingest.wildedge.dev/`. Treat it as a secret. Create a separate project key for each integration you may need to revoke on its own. ## Events An **event** is one thing that happened, recorded with its time, model, device, and measurements. | Event | Records | | --- | --- | | `inference` | One model call: timing, tokens, input and output measurements, predictions | | `model_load`, `model_download`, `model_unload` | A model's lifecycle on the device | | `error` | A failure, with its code and message | | `feedback` | A user's reaction to an inference, such as thumbs up or an edit | | `span` | A timed step in your application, such as a retrieval or a tool call | Events come from two sources. The **SDK** runs in your app and records local and cloud model calls, with device and hardware context. A **gateway** such as LiteLLM, OpenRouter, or Bifrost exports the cloud calls that pass through it, with no change to your app. See [Choose your setup](/). The [telemetry reference](/telemetry) lists every field. ## Runs, traces, and spans A **run** is one execution of a workflow or agent, for example one car scan or one support conversation turn. Its events and spans share a `run_id`. A **span** is a timed step inside a run, such as an agent step, a tool call, or a retrieval. Spans nest, and with the run's model calls they form the **trace** you see on the run's page: [![A run's trace in WildEdge: a scan step with detect, classify, and recognize spans, two on-device models, a model load, and a Gemini call](/images/concepts-run-waterfall.png)](/images/concepts-run-waterfall.png) If you know OpenTelemetry: a run is a trace, a span is a span, and an inference event is a leaf span that carries model data. Runs and spans come from `wildedge.trace()` and `wildedge.span()` in the SDK, or the Swift and Kotlin equivalents. ## Attachments By default WildEdge records measurements, not content. An **attachment** is an input or output file, such as an image, an audio clip, or text, that you choose to upload with an inference event. Each attachment has a role: `input` or `output`. Attachment capture is off until you enable it in **Project Settings** and in your SDK. Upload size, count, and retention depend on your plan. See [Captured content](/what-we-collect#captured-content). ## SQL and charts Every project has one queryable table, `events`. Open **SQL** to run read-only SQL against it, limited to the project and the selected time window. ```sql SELECT model_name, quantile_cont(duration_ms, 0.95) AS p95_ms, count(*) AS calls FROM events WHERE event_type = 'inference' GROUP BY model_name ORDER BY p95_ms DESC ``` * **Write SQL or build without it.** **Analytics** has a builder with filters and axes. **SQL** takes raw queries. * **Ask in plain language.** Describe what you want, for example "average latency by device model last 7 days", and WildEdge generates the SQL. This uses an AI provider key you add in **Settings**. * **Save as a chart.** A saved query becomes a **chart**: a table, a stat, a line, or a bar. You can download results as CSV. Your agent can do the same through MCP: `sql_schema` lists columns and `sql_query` runs a query. ## Dashboards A **dashboard** is a page of **panels**. Each panel shows one saved chart, and the whole dashboard follows one time window. The same chart can appear on several dashboards. Editing the chart updates it everywhere. Build dashboards in **Dashboards**, or ask your agent: `create_chart` saves a SQL chart and `add_dashboard_panel` places it. ## Datasets A **dataset** is a curated set of events with their attachments, for evaluation or fine-tuning. You can fill one in two ways: * **Build from filters.** Select events by time range, model, version, device, prediction label, confidence range, or error code, preview the result, then build. * **Add events by hand** from the **Events** list, one or many at a time, or from an event's page. Each row carries the event's predicted label. You can override the label for a row inside a dataset without changing the original event. A dataset shows how many rows have an input and an output attachment. Datasets need attachment capture. Without it, there is nothing to train on. See [Build evaluation datasets](/what-we-collect#model-behavior). ## Training export A **training integration** connects a project to an external training service. **Edge Impulse** is supported today. 1. In **Training**, add an integration with your Edge Impulse API key. WildEdge verifies it. 2. Start an **export job** for a dataset. WildEdge uploads the dataset's image attachments with their labels to your Edge Impulse project. You can force one label for every image. 3. Follow the job's progress and result in **Training**. Training integrations may need to be enabled for your project. Contact us if **Training** is not available. ## Glossary | Term | Meaning | Similar to | | --- | --- | --- | | Company | Your organization, team, and billing | Organization, workspace | | Project | Telemetry for one app or environment | Project | | DSN | Write-only key that sends events to a project | Sentry DSN, ingestion key | | Event | One recorded occurrence: inference, load, error, feedback, span | Log record, span | | Run | One workflow or agent execution, grouped by `run_id` | Trace, session | | Span | A timed step inside a run | Span | | Attachment | An opt-in input or output file on an inference | Payload, blob | | Chart | A saved query with a visualization | Saved query, insight | | Dashboard | A page of chart panels over one time window | Dashboard, board | | Dataset | Curated events with attachments and labels | Dataset | | Export job | One upload of a dataset to a training service | Sync | ## Next * Send your first event: [on-device quickstart](/quickstart/on-device) or [cloud API quickstart](/quickstart/cloud). * [Investigate events and traces](/investigate). * [Connect your AI agent](/connect-agent) to query, chart, and build dashboards for you. --- --- url: https://docs.wildedge.dev/integration-coverage.md description: >- Automatic telemetry, manual tracking, captured content, and delivery behavior by collection path. --- # Integration coverage The [telemetry reference](/telemetry) lists accepted fields. An integration sends only the fields it can observe. Runtime, provider, SDK version, and configuration determine which values arrive. ## Choose a collection path | Source | Automatic collection | Additional instrumentation | Limits | | --- | --- | --- | --- | | Python SDK | Enabled library integrations record supported model calls and metadata | Manual tracking for unsupported calls, feedback, spans, and attachments | Each adapter covers specific library entry points | | iOS / macOS SDK | Supported interceptors include ONNX Runtime, ML Kit, and ExecuTorch LLM | Handle APIs for other runtimes and application events | Platform and interceptor support vary | | Android SDK | Decorated runtime calls record supported inference telemetry | Wrap supported runtimes or use model handles and tracking APIs | Installing the dependency does not instrument every call | | LiteLLM export | Exported provider calls become inference events | SDK tracking for local calls or application context | Cache hits are not exported. Reported cost is estimated | | OpenRouter Broadcast | Exported requests become inference events | SDK tracking for local calls or application context | Rejections before routing and failed fallback attempts are not exported | | Bifrost export | Exported provider attempts become inference events | SDK tracking for local calls or application context | Reported cost is estimated. Unpriced models have no cost | Gateway exports do not supply the calling device's hardware state or application feedback. SDK and gateway events are not automatically linked into one trace. Disable SDK tracking for cloud calls exported by the gateway if you want one event per call. ## Python library examples | Integration | Verified behavior | Details | | --- | --- | --- | | OpenAI | Chat calls, Responses, and embeddings have dedicated instrumentation. Streaming metadata depends on the API and response | [Streaming](https://github.com/wild-edge/wildedge-python/blob/main/docs/streaming.md) | | Anthropic | Message calls and native streaming helpers are instrumented | [Streaming](https://github.com/wild-edge/wildedge-python/blob/main/docs/streaming.md) | | llama.cpp | Completion and chat entry points record inference telemetry. Prompts and replies are not attached automatically | [Examples](https://github.com/wild-edge/wildedge-python/blob/main/examples/gguf_example.py) | | ONNX Runtime | Supported session calls record inference timing. Input measurements and prediction extraction depend on input and output shape | [Example](https://github.com/wild-edge/wildedge-python/blob/main/examples/onnx_example.py) | | MLX Whisper and faster-whisper | Model loads and transcriptions are tracked. Audio and transcript attachments require manual tracking | [Whisper guide](https://github.com/wild-edge/wildedge-python/blob/main/docs/whisper.md) | | Other HTTP clients | `wildedge.llm_api()` records a wrapped call. Supply usage and response metadata through its API | [HTTP tracking](https://github.com/wild-edge/wildedge-python/blob/main/docs/llm_api.md) | These examples cover Python SDK v0.3.0. They are not a complete list of integrations. Check the [SDK compatibility guide](https://github.com/wild-edge/wildedge-python/blob/main/docs/compatibility.md) before enabling an adapter. ## Mobile runtime support Use the platform guide for supported entry points and metadata. A runtime name alone does not guarantee hardware, prediction, or content capture support. * [iOS / macOS SDK](https://github.com/wild-edge/wildedge-swift): interceptor setup, manual model handles, tracing, and examples. * [Android SDK](https://github.com/wild-edge/wildedge-android): runtime decorators, manual tracking, and examples. Compare reported device models and accelerators. Do not infer a specific chipset or NPU execution from a generic accelerator value. ## Content capture Python automatic integrations do not attach raw inputs or outputs. Enabling `attachments_enabled` permits uploads explicitly supplied to `track_inference(attachments=[...])`. Project attachment support must also be enabled. Other SDKs have their own attachment APIs and settings. Follow the platform guide. Do not assume Python configuration applies to mobile SDKs. Summaries, attributes, errors, URLs, and custom fields can contain content independently of attachments. See [content and identifiers](/telemetry#content-and-identifiers). WildEdge keeps gateway prompt and response text as event summaries only when the gateway exports it. LiteLLM leaves it out by default, Bifrost with `disable_content_logging`, and OpenRouter in Privacy Mode. ## Buffering and delivery SDK buffering and gateway exporter retries are separate mechanisms. | Collection path | Behavior | | --- | --- | | Python SDK | Configurable batches, flush interval, memory queue, and event age. Offline persistence is enabled by default. Dead-letter persistence is optional | | Mobile SDKs | Use the platform guide for queue, persistence, and shutdown behavior. Python defaults do not apply | | Gateway export | WildEdge acknowledges after storage. Exporter retry windows are finite, so an extended outage can lose batches | | Attachments | File upload is separate from event delivery. A recorded inference does not prove its attachment uploaded | For Python settings and defaults, see [Configuration](https://github.com/wild-edge/wildedge-python/blob/main/docs/configuration.md). Retryable transmitter failures include HTTP 429, server errors, and network errors. Queue and age limits mean persistence is not an unlimited delivery guarantee. For retries and known limitations of each gateway, see its setup page: [LiteLLM](/gateways/litellm), [OpenRouter](/gateways/openrouter), or [Bifrost](/gateways/bifrost). ## Verify your setup 1. Run one call through each enabled integration. 2. Find the event in the intended project. 3. Check the fields needed for your investigation. 4. If a field is absent, check adapter support before treating it as a model or device issue. ## Next * [Telemetry reference](/telemetry): every accepted field. * [Troubleshooting guide](/what-we-collect): which fields answer which question. --- --- url: https://docs.wildedge.dev/investigate.md description: >- Start from recent events, find a suspicious inference, and inspect the context that explains it, in WildEdge or with your AI agent. --- # Investigate events and traces Start with a small set of recent events, find a suspicious inference, then inspect the context available to explain it. New to events, runs, and spans? See [How WildEdge works](/concepts). Use [Troubleshooting guide](/what-we-collect) to choose fields for the problem you are investigating. ## 1. Find recent events Open **Events** in your [WildEdge project](https://app.wildedge.dev/), or [connect your AI agent](/connect-agent) and ask: > For project `PROJECT` in company `COMPANY`, inspect up to 25 events from the last 24 hours. Highlight failures and unusually long durations. Do not make any changes. Name the project and time window so the investigation stays focused. Your agent reasons over the bounded events it retrieves, not automatically over every event in your account. ## 2. Inspect an inference > Open event `event-id` from the previous result. Explain the errors, timing, and available telemetry. Describe any captured inputs and outputs that are available. SDK inputs and outputs require capture to be enabled. Gateway prompt and response text is kept only when the gateway exports it. Missing data should not be treated as evidence that a call succeeded or had no cost. ## 3. Follow the surrounding trace > If this event belongs to a run, follow the run trace and summarize where the problem started. Identify any gaps in the evidence. SDK and gateway events are not automatically linked into one trace. See [the combined setup guide](/setup/sdk-and-gateway) for the current limitation. ## Investigate gateway calls Ask your agent to filter by gateway and inspect provider, model, token use, latency, and reported cost where available. Gateway reporting differs by provider. See [gateway fields](/llm-gateways#query-gateway-events) before interpreting totals. ## Next * [Troubleshooting guide](/what-we-collect): which fields explain failures, latency, cost, and device issues. * Keep what you found: save a query as a [chart or dashboard](/concepts#sql-and-charts), or add the events to a [dataset](/concepts#datasets). --- --- url: https://docs.wildedge.dev/quickstart/cloud.md description: >- Send your first inference event to WildEdge from an OpenAI call in about 2 minutes. Works with any OpenAI-compatible provider. --- # Quickstart: cloud API Call OpenAI from Python and see the call in WildEdge, with latency, token use, model, and provider. **Expected time:** 2 minutes. **You need:** Python 3.10+, [uv](https://docs.astral.sh/uv/), and an OpenAI API key. Running models locally instead? See the [on-device quickstart](/quickstart/on-device). Using LiteLLM or OpenRouter as a gateway? See [Gateway setup](/llm-gateways). ## 1. Get your DSN Sign in to [WildEdge](https://app.wildedge.dev/) and create a project. Open **API Keys** and select **Reveal DSN** on the project key. Copy it. The DSN looks like this: ```text https://@ingest.wildedge.dev/ ``` ## 2. Install ```bash uv init wildedge-quickstart && cd wildedge-quickstart uv add wildedge-sdk openai ``` ## 3. Call a model Save this as `app.py`: ```python import wildedge from openai import OpenAI # Initialize before creating the client so the integration can track it. wildedge.init(integrations=["openai"]) client = OpenAI() response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Explain how rain forms in one sentence."}], ) print(response.choices[0].message.content) wildedge.flush() # Send now. Events are otherwise batched every 60 seconds. ``` Set your keys and run it: ```bash export WILDEDGE_DSN="https://@ingest.wildedge.dev/" export OPENAI_API_KEY="sk-..." uv run python app.py ``` ::: tip Prompts and outputs stay local The reply prints in your terminal. It is not uploaded. WildEdge records timing, token use, and model metadata. Content capture is opt-in. See [Captured content](/what-we-collect#captured-content). ::: ::: details Using another OpenAI-compatible provider? Set `base_url` on the client. WildEdge records the provider on every event. For example, Groq: ```python import os client = OpenAI( base_url="https://api.groq.com/openai/v1", api_key=os.environ["GROQ_API_KEY"], ) ``` Fireworks, Together, Mistral, DeepSeek, Gemini, Azure OpenAI, and others work the same way. See the [provider list](https://github.com/wild-edge/wildedge-python/blob/main/docs/providers.md). For Anthropic, use `integrations=["anthropic"]` and the Anthropic client. ::: ## 4. See your event Open **Events** in your WildEdge project. Select the new inference event to see its duration, token counts, model, and provider. ![Events list in WildEdge showing inference events with model and device metadata](/images/quickstart-events.jpg) *Example from a mobile app. Your list will show the gpt-4o-mini call.* No events? Check that `WILDEDGE_DSN` is set in the same shell. Without a DSN the SDK does nothing and raises no error. See [Missing events or fields](/what-we-collect#missing-events-or-fields). ## Next steps * **Learn the building blocks.** [How WildEdge works](/concepts) explains projects, events, runs, SQL charts, dashboards, and datasets. * **Instrument your own app.** Call `wildedge.init(integrations=[...])` before you create API clients. Use `openai`, `anthropic`, or both. * **Stream responses.** Streaming calls record time to first token. See [streaming](https://github.com/wild-edge/wildedge-python/blob/main/docs/streaming.md). * **Add a local model.** Follow the [on-device quickstart](/quickstart/on-device), then group local and remote calls into one trace with `wildedge.trace()`. See [manual tracking](https://github.com/wild-edge/wildedge-python/blob/main/docs/manual-tracking.md#track-spans-for-agentic-workflows). * **Ask your agent.** [Connect Claude Code, Codex, or ChatGPT](/connect-agent) and ask it to explain your first event. --- --- url: https://docs.wildedge.dev/quickstart/on-device.md description: >- Send your first inference event to WildEdge from Python in about 5 minutes. Runs a small local model on CPU, no model API key needed. --- # Quickstart: on-device model Run a small language model on your laptop and see the inference event in WildEdge, including the model load and the hardware it ran on. **Expected time:** 5 minutes. **You need:** Python 3.10+ and [uv](https://docs.astral.sh/uv/). No GPU and no model API key. Calling OpenAI or another hosted API instead? See the [cloud API quickstart](/quickstart/cloud). Building for iOS, macOS, or Android? See [Set up app telemetry](/setup/sdk). ## 1. Get your DSN Sign in to [WildEdge](https://app.wildedge.dev/) and create a project. Open **API Keys** and select **Reveal DSN** on the project key. Copy it. The DSN looks like this: ```text https://@ingest.wildedge.dev/ ``` ## 2. Install Create a project and add the SDK, Transformers, and the CPU build of PyTorch: ```bash uv init wildedge-quickstart && cd wildedge-quickstart uv add wildedge-sdk transformers uv add torch --index pytorch-cpu=https://download.pytorch.org/whl/cpu ``` The CPU build skips about 2 GB of CUDA libraries that Linux installs by default. The model runs on CPU either way. ## 3. Run a model Save this as `app.py`: ```python import wildedge from transformers import pipeline # Initialize before creating the model so the integration can track it. wildedge.init(integrations=["transformers"]) model = pipeline( "text-generation", model="HuggingFaceTB/SmolLM2-360M-Instruct", device=-1, # CPU ) result = model( "Explain how rain forms in one sentence.", max_new_tokens=32, do_sample=False, return_full_text=False, ) print(result[0]["generated_text"]) wildedge.flush() # Send now. Events are otherwise batched every 60 seconds. ``` Set your DSN and run it: ```bash export WILDEDGE_DSN="https://@ingest.wildedge.dev/" uv run python app.py ``` The first run downloads the model (about 700 MB) from Hugging Face. ::: tip Prompts and outputs stay local The generated text prints in your terminal. It is not uploaded. WildEdge records timing, model metadata, and hardware context. Content capture is opt-in. See [Captured content](/what-we-collect#captured-content). ::: ## 4. See your event Open **Events** in your WildEdge project. You should see two events: a model load and an inference. Select the inference to see its duration, model, and the device it ran on. ![Events list in WildEdge showing inference events with model and device metadata](/images/quickstart-events.jpg) *Example from a mobile app. Your list will show the SmolLM2 load and inference.* No events? Check that `WILDEDGE_DSN` is set in the same shell. Without a DSN the SDK does nothing and raises no error. See [Missing events or fields](/what-we-collect#missing-events-or-fields). ## Next steps * **Learn the building blocks.** [How WildEdge works](/concepts) explains projects, events, runs, SQL charts, dashboards, and datasets. * **Instrument your own app.** Call `wildedge.init(integrations=[...])` before you create models or API clients. Pick keys from the [integration list](https://github.com/wild-edge/wildedge-python#supported-integrations), for example `openai`, `anthropic`, `llama_cpp`, or `mlx`. * **Skip code changes.** Start an existing app with `wildedge run --integrations llama_cpp -- python app.py`. See the [deployment guide](https://github.com/wild-edge/wildedge-python/blob/main/docs/deployment.md). * **Trace a workflow.** Group local and remote calls into one run with `wildedge.trace()` and `wildedge.span()`. See [manual tracking](https://github.com/wild-edge/wildedge-python/blob/main/docs/manual-tracking.md#track-spans-for-agentic-workflows). * **Add a cloud call.** Follow the [cloud API quickstart](/quickstart/cloud), then group local and remote calls into one trace. * **Ask your agent.** [Connect Claude Code, Codex, or ChatGPT](/connect-agent) and ask it to explain your first event. * **Go mobile.** [Set up the iOS / macOS or Android SDK](/setup/sdk). --- --- url: https://docs.wildedge.dev/setup/sdk-and-gateway.md description: >- Record on-device inference with an SDK and cloud calls through your LLM gateway without counting the same call twice. --- # Set up app and gateway telemetry Use both when your application runs models itself and also sends remote calls through an LLM gateway. Decide which source records each call before enabling telemetry. ::: tip Avoid duplicate cloud events If your gateway exports cloud model calls, disable SDK tracking for those calls to avoid counting them twice. Keep SDK tracking enabled for on-device models and calls the gateway does not export. SDK tracking for on-device models and gateway tracking for cloud models do not overlap. ::: ## 1. Decide which source records each call For apps with local and remote inference: | Inference path | Record with | | --- | --- | | On-device or local model | WildEdge SDK | | Remote model through LiteLLM, OpenRouter, or Bifrost | Gateway export | Enable only the SDK integrations that cover calls your gateway does not already record. For example, in Python, enable only the llama.cpp integration: ```sh wildedge run --integrations llama_cpp ``` `wildedge run` enables every integration by default, including OpenAI and Anthropic. Do not leave those enabled for calls that your gateway also exports. For other platforms, configure SDK tracking so it does not record calls exported by the gateway. ## 2. Configure both sources 1. Follow [Set up app telemetry](/setup/sdk) for your application's platform. 2. Follow [Set up gateway telemetry](/llm-gateways) for LiteLLM, OpenRouter, or Bifrost. 3. Use the same WildEdge project if you want to inspect both sources there, with separate project keys so you can revoke either independently. SDK capture is opt-in. Gateway prompt and response text is kept only when the gateway exports it. See [Set up gateway telemetry](/llm-gateways). ## 3. Verify each inference path Run one local inference and one remote request through the gateway. Open **Events** in your project and confirm that each path produces its expected event. Gateway events populate the `gateway` field. SDK events leave it empty. Check that each cloud call exported by the gateway produces one event. If the SDK also records it, disable SDK tracking for that call. ## Next: investigate [Connect your AI agent](/connect-agent) and ask it to inspect local and gateway events separately. Do not expect a single linked trace across both sources. --- --- url: https://docs.wildedge.dev/setup/sdk.md description: >- Record inference calls in your application with the Python, iOS / macOS, or Android SDK, then confirm your first event arrives. --- # Set up app telemetry Use a WildEdge SDK to record inference calls in your application, including on-device models. Choose your platform, configure your project credentials, then confirm that events arrive. Trying WildEdge for the first time? The Python quickstarts for an [on-device model](/quickstart/on-device) or a [cloud API](/quickstart/cloud) get you to a first event in a few minutes. If your gateway also sends telemetry to WildEdge, follow [Set up app and gateway telemetry](/setup/sdk-and-gateway) to avoid recording the same call twice. ## 1. Choose your platform | Platform | Setup guide | Examples | | --- | --- | --- | | Python | [Install and configure](https://github.com/wild-edge/wildedge-python#install) | [Python examples](https://github.com/wild-edge/wildedge-python/tree/main/examples) | | iOS / macOS | [Getting started](https://github.com/wild-edge/wildedge-swift#getting-started) | [Swift examples](https://github.com/wild-edge/wildedge-swift/tree/main/Examples) | | Android | [Quick start](https://github.com/wild-edge/wildedge-android#quick-start) | [Android samples](https://github.com/wild-edge/wildedge-android/tree/main/samples) | The platform guides contain the installation commands and supported integrations. ## 2. Configure your project credentials Sign in to [WildEdge](https://app.wildedge.dev/), open your project, then open **API Keys** and select **Reveal DSN** on a project key. Configure that DSN using your platform guide. Keep credentials out of source control. Use separate project keys for integrations you may need to revoke independently. ## 3. Choose what to capture Input and output capture is opt-in. Follow your SDK guide to configure capture or supply attachments through its tracking API. Support varies by integration. See [Captured content](/what-we-collect#captured-content) for the ways content can reach WildEdge. ## 4. Check your first event Run one inference through an integration enabled in your SDK. Open **Events** in your WildEdge project and find the new event. Check the model, timing, and available telemetry. Captured inputs and outputs are available only when capture is enabled and supported by the integration. ## Next: investigate [Connect your AI agent](/connect-agent), or [investigate events and traces](/investigate) in your project. --- --- url: https://docs.wildedge.dev/gateways/bifrost.md description: Send model calls from Bifrost to WildEdge with its otel plugin. --- # Set up Bifrost Bifrost sends traces with its `otel` plugin. Add the snippet below to your config to enable tracing. Verified on Bifrost v2.5.1. ## 1. Find your project secret 1. Sign in to [WildEdge](https://app.wildedge.dev/) and open the project that should receive the events. 2. Open **API Keys** and select **Reveal DSN** on a project key. The DSN looks like this: ```text https://@ingest.wildedge.dev/ ``` The part between `https://` and `@` is your project secret. You need only the secret. ::: warning Protect the secret Anyone with the secret can send events to your project. Keep it in your secret store, not in source control. Use a separate project key for the gateway, so you can revoke it without affecting your apps. ::: ## 2. Add the otel plugin Add the plugin to the `plugins` list in Bifrost's `config.json`, then restart Bifrost: ```json "plugins": [ { "enabled": true, "name": "otel", "config": { "service_name": "bifrost", "collector_url": "https://ingest.wildedge.dev/api/otlp/v1/traces", "trace_type": "genai_extension", "protocol": "http", "headers": { "X-Project-Secret": "" }, "disable_content_logging": true } } ] ``` * `collector_url` is the full traces URL, including `/v1/traces`. * `trace_type` must be `genai_extension`. It follows the OpenTelemetry GenAI conventions, which WildEdge reads. * `protocol` must be `http`. WildEdge doesn't accept OTLP over gRPC. * To keep the secret out of `config.json`, set the header value to `"env.WILDEDGE_PROJECT_SECRET"` and put the secret in that environment variable. * `disable_content_logging: true` leaves prompt and response text out of the export, and tool names too. If you turn it off, WildEdge keeps the end of the prompt and the start of the response as the event's input and output summaries. * `service_name` names the gateway in your traces. Use any name you like. * Leave `metrics_enabled` off. WildEdge accepts traces only. ## 3. Check that events arrive Send one request through Bifrost: ```sh curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}' ``` Use your Bifrost address and a provider and model you configured in it. Open **Events** in WildEdge. Events appear within a few minutes, one inference event per provider attempt. ## What you get * `gateway` is `bifrost`, and `model_provider` is the provider that served the attempt, for example `openai`. * Each provider attempt is its own event, including each retry and fallback. `request_id` is Bifrost's request ID, shared by every attempt of one request. A request rescued by a retry or a fallback counts as one successful request. * `reported_cost_amount` is Bifrost's estimate from its price table, in USD, so `reported_cost_is_estimated` is `true`. Bifrost reports a cost of 0 for models missing from that table, and no cost for failed calls. WildEdge records both as unknown. * Failed attempts record the provider's HTTP status and error code, for example a `429` when the provider rate limits. * Time to first token is recorded on streamed calls. * MCP tool calls, from Agent Mode, `/v1/mcp/tool/execute` or the `/mcp` gateway, appear in the trace as tool spans. See [Query gateway events](/llm-gateways#query-gateway-events) for the columns and an example query. ## Known limitations * **Chat and text completions only.** Embeddings, speech, transcription and image calls aren't recorded. * **Cache hits.** Bifrost's cache answers without calling a provider and exports no model call, so cache hits don't appear. * **Tool names.** With `disable_content_logging: true`, Bifrost leaves tool names out, so tool calls appear as `unknown`, with their MCP server. ## Retries Bifrost doesn't retry. It sends each request's trace once, with a 5 second timeout. Set `export_timeout` in the plugin config to change it, up to 60. After 5 failures in a row it stops sending for 30 seconds. ## Troubleshooting If Bifrost requests succeed but no events appear, look for `failed to emit trace` in Bifrost's logs. See [status codes](/llm-gateways#troubleshooting) for what each HTTP status means. ## Next * [Investigate events and traces](/investigate), or [connect your AI agent](/connect-agent) to do it for you. * Also using a WildEdge SDK? Follow [App + gateway](/setup/sdk-and-gateway) so each call is recorded once. --- --- url: https://docs.wildedge.dev/llm-gateways.md description: >- Send model calls from an LLM gateway to WildEdge over OpenTelemetry, from LiteLLM, OpenRouter or Bifrost. --- # Set up gateway telemetry If your app reaches LLM providers through a gateway, the gateway can send WildEdge a record of every model call. You don't need to change your app or install an SDK. The gateway exports OpenTelemetry (OTLP) traces, and WildEdge turns each model call into an inference event. Each event records: * the provider and the model that served the call * input, output, cached and reasoning tokens, when the gateway reports them * latency, and time to first token for streamed calls * whether the call succeeded, and the error code when it failed * the gateway and its service name, and the model name your app asked the gateway for * the cost the gateway reports, when it reports one When the gateway runs MCP tools, each tool call appears in the trace as a tool span, with the tool name, the MCP server, its duration and whether it failed. Tool arguments and results are never kept. When a gateway includes prompt and response text in its traces, WildEdge keeps it as the event's input and output summaries. Each gateway's setup says how to leave it out. WildEdge accepts traces only. Don't send OpenTelemetry metrics or logs to it. See [Troubleshooting guide](/what-we-collect) for guidance on failures, latency, usage, and cost. ## LiteLLM LiteLLM proxy 1.106.6, configured with environment variables. [Set up LiteLLM](/gateways/litellm) ## OpenRouter OpenRouter Broadcast, configured in the OpenRouter dashboard. [Set up OpenRouter](/gateways/openrouter) ## Bifrost Bifrost v2.5.1, configured with its `otel` plugin. [Set up Bifrost](/gateways/bifrost) ## Query gateway events Gateway events have their own columns, which you can use in SQL on the **Analytics** page or through [MCP](./mcp). They are empty on events from the SDKs. | Column | What it holds | | --- | --- | | `gateway` | The gateway that reported the call, for example `litellm`. | | `service_name` | The service name you set on the gateway. | | `model_provider` | The provider that served the call, for example `openai`. | | `requested_model_id` | The model name your app sent to the gateway. | | `request_id` | One gateway request, where the gateway reports it. | | `reported_cost_amount` | The cost the gateway reports, as an exact decimal. | | `reported_cost_currency` | The currency of that cost, for example `USD`. | | `reported_cost_is_estimated` | `true` when the gateway priced the call itself. | What each gateway puts in these columns is on its setup page. For example, the cost and token use per requested model over the selected time range: ```sql SELECT gateway, requested_model_id, model_name, COUNT(*) AS calls, SUM(tokens_in) AS tokens_in, SUM(tokens_out) AS tokens_out, SUM(reported_cost_amount) AS cost_usd FROM events WHERE gateway IS NOT NULL AND reported_cost_currency = 'USD' GROUP BY ALL ORDER BY cost_usd DESC ``` Calls without a reported cost have no currency, so the filter leaves them out. Count them separately with `reported_cost_amount IS NULL`. ## Troubleshooting When an export fails, the gateway logs the HTTP status: | Status | Meaning | What to do | | --- | --- | --- | | `401` | The secret is missing or wrong. | Check the `X-Project-Secret` header, and that the project key isn't revoked. | | `404` | Wrong endpoint. | Check the endpoint against your gateway's setup page. | | `413` | The export is too large. | Send smaller batches, or leave prompt and response text out. | | `415` | Unsupported encoding. | Send OTLP over HTTP as protobuf or JSON. | | `429` | Too many requests for this project key. | Check your gateway's retries. If it persists, contact us. | | `503` | WildEdge couldn't store the events yet. | Check your gateway's retries. | When WildEdge answers `429` or `503`, it adds a `Retry-After` of a second or two. Whether the gateway retries, and for how long, is on its setup page. Events in an export the gateway drops are lost. ## Next: investigate [Connect your AI agent](/connect-agent), or follow [Investigate events and traces](/investigate). If your app also uses an SDK, check the [combined setup guide](/setup/sdk-and-gateway) to avoid recording the same call twice. --- --- url: https://docs.wildedge.dev/gateways/litellm.md description: Send model calls from the LiteLLM proxy to WildEdge over OpenTelemetry. --- # Set up LiteLLM The LiteLLM proxy sends traces with its OpenTelemetry export. Verified on LiteLLM 1.106.6. ## 1. Find your project secret 1. Sign in to [WildEdge](https://app.wildedge.dev/) and open the project that should receive the events. 2. Open **API Keys** and select **Reveal DSN** on a project key. The DSN looks like this: ```text https://@ingest.wildedge.dev/ ``` The part between `https://` and `@` is your project secret. You need only the secret. ::: warning Protect the secret Anyone with the secret can send events to your project. Keep it in your secret store, not in source control. Use a separate project key for the gateway, so you can revoke it without affecting your apps. ::: ## 2. Configure the LiteLLM proxy Set these environment variables on the LiteLLM proxy, then restart it: ```sh LITELLM_OTEL_V2=true OTEL_EXPORTER=http/protobuf OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.wildedge.dev/api/otlp OTEL_EXPORTER_OTLP_HEADERS=X-Project-Secret= OTEL_SERVICE_NAME=litellm ``` * `LITELLM_OTEL_V2=true` turns on LiteLLM's OpenTelemetry export. It follows the OpenTelemetry GenAI conventions, which WildEdge reads. * `OTEL_EXPORTER` picks the encoding. `http/json` works too. * The exporter adds `/v1/traces` to the endpoint itself. Don't add it yourself. * If your setup can only set an `Authorization` header, use `Authorization=Bearer ` in place of `X-Project-Secret=`. * `OTEL_SERVICE_NAME` names the gateway in your traces. Use any name you like. LiteLLM leaves prompt and response text out of the export unless you set `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`. You don't need to change the LiteLLM config file. ## 3. Check that events arrive Send one request through the proxy: ```sh curl http://localhost:4000/v1/chat/completions \ -H "Authorization: Bearer $LITELLM_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "", "messages": [{"role": "user", "content": "Hello"}]}' ``` Use your proxy's address, one of your LiteLLM keys and a model name from your LiteLLM config. Open **Events** in WildEdge. Events appear within a few minutes. You should see an inference event for the provider model that served the request. It carries the request's token counts and latency. ## What you get * `gateway` is `litellm`, and `model_provider` is the provider that served the call, for example `openai`. * `requested_model_id` is the model name your app sent, and `model_name` is the provider model LiteLLM routed it to. * `request_id` is LiteLLM's call ID. A failed attempt and its fallback share it. * `reported_cost_amount` is LiteLLM's estimate from its price list, in USD, so `reported_cost_is_estimated` is `true`. Models missing from the price list and failed calls have no cost. * When the provider doesn't report usage, LiteLLM exports zero tokens. WildEdge records these token counts as unknown, not as zero. * A stream your app cancels is recorded as failed, with error code `STREAM_CANCELLED` and no token counts. * MCP tool calls, through LiteLLM's `/mcp` gateway or run for a chat completion, appear in the trace as tool spans. See [Query gateway events](/llm-gateways#query-gateway-events) for the columns and an example query. ## Known limitations * **Cache hits.** LiteLLM doesn't export a model call when it answers from its cache, so cache hits don't appear. * **Tool loops.** When LiteLLM runs an MCP tool for a chat completion, it doesn't export the model call that reads the tool result. That call and its tokens are missing. ## Retries LiteLLM retries `429`, `502`, `503`, `504` and connection errors with backoff, for up to 10 seconds in total. Set `OTEL_EXPORTER_OTLP_TIMEOUT` to change it. Then it drops the batch. ## Troubleshooting LiteLLM logs export failures, for example `Failed to export spans batch`, with the HTTP status. See [status codes](/llm-gateways#troubleshooting). * `404`: check that the endpoint is `https://ingest.wildedge.dev/api/otlp`, without `/v1/traces`. * `413`: lower `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`. * `415`: set `OTEL_EXPORTER` to `http/protobuf` or `http/json`. If requests succeed but no events appear, check that your LiteLLM version is supported and that `LITELLM_OTEL_V2=true` is set on the proxy process. ## Next * [Investigate events and traces](/investigate), or [connect your AI agent](/connect-agent) to do it for you. * Also using a WildEdge SDK? Follow [App + gateway](/setup/sdk-and-gateway) so each call is recorded once. --- --- url: https://docs.wildedge.dev/gateways/openrouter.md description: Send model calls from OpenRouter to WildEdge with Broadcast. --- # Set up OpenRouter OpenRouter sends traces with its Broadcast feature. You set it up in the OpenRouter dashboard. Your app doesn't change. ## 1. Find your project secret 1. Sign in to [WildEdge](https://app.wildedge.dev/) and open the project that should receive the events. 2. Open **API Keys** and select **Reveal DSN** on a project key. The DSN looks like this: ```text https://@ingest.wildedge.dev/ ``` The part between `https://` and `@` is your project secret. You need only the secret. ::: warning Protect the secret Anyone with the secret can send events to your project. Keep it in your secret store, not in source control. Use a separate project key for the gateway, so you can revoke it without affecting your apps. ::: ## 2. Add WildEdge as a Broadcast destination 1. In OpenRouter, open **Settings → Observability** and turn on **Enable Broadcast**. 2. Edit the **OpenTelemetry Collector** destination. 3. Set **Endpoint** to the full traces URL: ```text https://ingest.wildedge.dev/api/otlp/v1/traces ``` 4. Set **Headers** to: ```json {"X-Project-Secret": ""} ``` 5. Turn on **Privacy Mode**. Without it, each export carries the full prompt and response, which WildEdge keeps as the event's summaries. WildEdge also rejects exports over 2 MB. 6. Select **Test Connection**, then save. The test doesn't create an event. ## 3. Check that events arrive Send one request through OpenRouter with the API key you use in your app. Open **Events** in WildEdge. Events appear within a few minutes, one inference event per request. ## What you get * `gateway` and `model_provider` are both `openrouter`, because OpenRouter is the API you call and pay. The provider that served the call, for example `azure`, isn't a column yet. * `model_name` is OpenRouter's model ID, for example `openai/gpt-4o-mini`. * `reported_cost_amount` is what OpenRouter charged, in USD, so `reported_cost_is_estimated` is `false`. A stream your app cancels is charged, and its event is marked as failed. * `request_id` is OpenRouter's generation ID, the one shown in its activity log. * Time to first token is recorded on every call, streamed or not. It's how long the model took to start answering, measured by OpenRouter. See [Query gateway events](/llm-gateways#query-gateway-events) for the columns and an example query. ## Known limitations * **Fallbacks.** Each request is one event, for the model and provider that answered. Attempts that failed before a fallback aren't recorded. * **Requests OpenRouter rejects before routing,** for example with an unknown model ID. OpenRouter sends no trace for them. ## Retries OpenRouter retries failed deliveries from a queue. It doesn't document for how long. ## Troubleshooting OpenRouter saves a destination only after **Test Connection** passes. If it fails, check that the endpoint ends in `/v1/traces` and that the header is valid JSON. See [status codes](/llm-gateways#troubleshooting) for what each HTTP status means. ## Next * [Investigate events and traces](/investigate), or [connect your AI agent](/connect-agent) to do it for you. * Also using a WildEdge SDK? Follow [App + gateway](/setup/sdk-and-gateway) so each call is recorded once. --- --- url: https://docs.wildedge.dev/telemetry.md description: Accepted telemetry events, payload fields, types, units, and optional content. --- # Telemetry reference This page describes the SDK batch payload accepted by the ingest API. It does not promise that every SDK or integration records every field. See [Integration coverage](/integration-coverage) for collection paths and [Troubleshooting guide](/what-we-collect) to choose signals for a problem. Field paths here are payload paths. Analytics exposes a flattened representation, so SQL column names can differ. For example, payload `inference.output_meta.tokens_in` is queried as `tokens_in`. See the [API reference](https://app.wildedge.dev/api/docs) for request constraints and [gateway guide](/llm-gateways) for mapped gateway columns. ## Event types | Event | Payload block | Meaning | | --- | --- | --- | | `model_download` | `download` | Model weight transfer | | `model_load` | `load` | Model initialization | | `inference` | `inference` | One model invocation | | `model_unload` | `unload` | Model release | | `feedback` | `feedback` | Feedback linked to an inference | | `error` | `error` | A reported error | | `span` | `span` | A timed application step | The batch validator requires the corresponding payload block. Every event except `span` requires a `model_id` present in the batch model registry. A span may omit `model_id`. `memory_warning`, `accelerator_fallback`, and `context_truncation` are not accepted standalone event types in the current batch API. Do not assume SDK APIs or protocol proposals imply server support for those event types. ## Reading the field tables * **Required** means required by the ingest schema, not automatically collected. * **Optional** fields can be omitted or null. Treat missing measurements as unknown. * `int` is an integer, `float` is numeric, and `bool` is true or false. Arrays use `list[...]`. * Durations ending in `_ms` use milliseconds. Sizes ending in `_bytes` use bytes. CPU frequencies use MHz. Temperatures use Celsius. * Nested blocks have their own tables below. Their field names are relative to that block. ## Batch envelope | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `protocol_version` | `str` | Required | Protocol version. | | `device` | `DeviceInfoSchema` | Required | Nested payload. See the corresponding table. | | `models` | `dict[str, ModelRegistryEntrySchema]` | Required | Nested payload. See the corresponding table. | | `session_id` | `str` | Required | SDK session identifier. | | `batch_id` | `str` | Required | Batch id. | | `created_at` | `str` | Required | ISO 8601 batch creation time. | | `sent_at` | `str` | Required | ISO 8601 batch send time. | | `events` | `list[EventSchema]` | Required | Nested payload. See the corresponding table. | ## Event envelope | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `event_id` | `str` | Required | Event id. | | `event_type` | `str` | Required | Event type. | | `timestamp` | `str` | Required | ISO 8601 event time. | | `model_id` | `str` | Optional | Key into the batch model registry. | | `trace_id` | `str` | Optional | Trace id. | | `span_id` | `str` | Optional | Span id. | | `parent_span_id` | `str` | Optional | Parent span id. | | `run_id` | `str` | Optional | Run id. | | `agent_id` | `str` | Optional | Agent id. | | `step_index` | `int` | Optional | Step index. | | `conversation_id` | `str` | Optional | Conversation id. | | `attributes` | `object` | Optional | Flat scalar map. Nested objects and arrays are rejected. Event and span attributes share a configured size limit. | | `gateway` | `str` | Optional | Gateway. | | `telemetry` | `TelemetryContextSchema` | Optional | Nested payload. See the corresponding table. | | `service` | `ServiceContextSchema` | Optional | Nested payload. See the corresponding table. | | `request_id` | `str` | Optional | Request id. | | `requested_model_id` | `str` | Optional | Requested model id. | | `span_role` | `string enum` | Optional | gateway_request, provider_attempt, or internal. Role constraints apply. | | `reported_cost` | `ReportedCostSchema` | Optional | Gateway-reported amount and provenance. Not a universal SDK price calculation. | | `cache_hit` | `bool` | Optional | Cache hit. | | `retry_of_span_id` | `str` | Optional | Provider-attempt reference. Requires trace_id and span_id. | | `fallback_of_span_id` | `str` | Optional | Provider-attempt reference. Requires trace_id and span_id. | | `download` | `DownloadEventDataSchema` | Optional | Nested payload. See the corresponding table. | | `load` | `LoadEventDataSchema` | Optional | Nested payload. See the corresponding table. | | `inference` | `InferenceEventDataSchema` | Optional | Nested payload. See the corresponding table. | | `unload` | `UnloadEventDataSchema` | Optional | Nested payload. See the corresponding table. | | `feedback` | `FeedbackEventDataSchema` | Optional | Nested payload. See the corresponding table. | | `error` | `ErrorEventDataSchema` | Optional | Nested payload. See the corresponding table. | | `span` | `SpanEventDataSchema` | Optional | Nested payload. See the corresponding table. | | `attachments` | `list[AttachmentRefSchema]` | Optional | Nested payload. See the corresponding table. | | `custom` | `object` | Optional | Custom JSON. Review supplied values for sensitive content. | ## Device metadata | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `device_id` | `str` | Required | Identifier supplied by the SDK. Generation and hashing depend on the SDK. | | `device_type` | `str` | Required | android, ios, linux, windows, macos, or embedded. | | `device_model` | `str` | Optional | Device model. | | `os_version` | `str` | Optional | Os version. | | `app_version` | `str` | Optional | App version. | | `sdk_version` | `str` | Optional | Sdk version. | | `locale` | `str` | Optional | Locale. | | `timezone` | `str` | Optional | Timezone. | | `cpu_arch` | `str` | Optional | Cpu arch. | | `cpu_cores` | `int` | Optional | Cpu cores. | | `ram_total_bytes` | `int` | Optional | Bytes. | | `disk_total_bytes` | `int` | Optional | Bytes. | | `accelerators` | `list[str]` | Optional | Accelerators. | | `gpu_name` | `str` | Optional | Gpu name. | ## Model registry | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `model_name` | `str` | Required | Model name. | | `model_family` | `str` | Optional | Model family. | | `model_version` | `str` | Optional | Model version. | | `model_source` | `str` | Required | huggingface|local|mlkit|coreml|openai|openrouter|anthropic|google|api|custom | | `model_format` | `str` | Required | onnx|tflite|coreml|gguf|pytorch|safetensors|api | | `quantization` | `str` | Optional | f32|f16|int8|q4_0|q4_k_m|q8_0|none | | `provider` | `str` | Optional | Provider. | ## Inference | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `inference_id` | `str` | Required | Identifier for the inference. | | `duration_ms` | `int` | Required | Elapsed time in milliseconds. | | `input_modality` | `str` | Optional | image|audio|text|multimodal|structured | | `output_modality` | `str` | Optional | Output modality. | | `input_meta` | `InputMetaSchema` | Optional | Nested payload. See the corresponding table. | | `output_meta` | `OutputMetaSchema` | Optional | Nested payload. See the corresponding table. | | `generation_config` | `GenerationConfigSchema` | Optional | Nested payload. See the corresponding table. | | `hardware` | `HardwareContextSchema` | Optional | Nested payload. See the corresponding table. | | `api_meta` | `ApiMetaSchema` | Optional | Nested payload. See the corresponding table. | | `success` | `bool` | Required | Outcome reported by the producer. | | `error_code` | `str` | Optional | Error code. | ## Input measurements | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `width` | `int` | Optional | Width. | | `height` | `int` | Optional | Height. | | `channels` | `int` | Optional | Channels. | | `format` | `str` | Optional | Format. | | `source` | `str` | Optional | Source. | | `histogram_summary` | `HistogramSummarySchema` | Optional | Nested payload. See the corresponding table. | | `duration_ms` | `int` | Optional | Elapsed time in milliseconds. | | `sample_rate` | `int` | Optional | Audio sample rate in Hz. | | `bit_depth` | `int` | Optional | Bit depth. | | `codec` | `str` | Optional | Codec. | | `is_streaming` | `bool` | Optional | Is streaming. | | `snr_db` | `float` | Optional | Snr db. | | `volume_db` | `float` | Optional | Volume db. | | `speech_ratio` | `float` | Optional | Speech ratio. | | `clipping_detected` | `bool` | Optional | Clipping detected. | | `char_count` | `int` | Optional | Char count. | | `word_count` | `int` | Optional | Word count. | | `token_count` | `int` | Optional | Token count. | | `language` | `str` | Optional | Language. | | `language_confidence` | `float` | Optional | Language confidence. | | `encoding` | `str` | Optional | Encoding. | | `contains_code` | `bool` | Optional | Contains code. | | `prompt_type` | `str` | Optional | Prompt type. | | `turn_index` | `int` | Optional | Turn index. | ## Image statistics | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `brightness_mean` | `float` | Optional | Brightness mean. | | `brightness_stddev` | `float` | Optional | Brightness stddev. | | `brightness_buckets` | `list[int]` | Optional | Brightness buckets. | | `contrast` | `float` | Optional | Contrast. | | `saturation_mean` | `float` | Optional | Saturation mean. | | `blur_score` | `float` | Optional | Blur score. | | `noise_score` | `float` | Optional | Noise score. | ## Output measurements | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `task` | `str` | Optional | Task. | | `num_predictions` | `int` | Optional | Num predictions. | | `top_k` | `list[TopKPredictionSchema]` | Optional | Nested payload. See the corresponding table. | | `avg_confidence` | `float` | Optional | Avg confidence. | | `tokens_in` | `int` | Optional | Tokens in. | | `tokens_out` | `int` | Optional | Tokens out. | | `cached_input_tokens` | `int` | Optional | Cached input tokens. | | `cache_write_input_tokens` | `int` | Optional | Nonnegative integer. | | `reasoning_tokens_out` | `int` | Optional | Reasoning tokens out. | | `time_to_first_token_ms` | `int` | Optional | Milliseconds. | | `tokens_per_second` | `float` | Optional | Tokens per second. | | `stop_reason` | `str` | Optional | Stop reason. | | `context_used` | `int` | Optional | Context used. | | `avg_token_entropy` | `float` | Optional | Avg token entropy. | | `safety_triggered` | `bool` | Optional | Safety triggered. | | `dimensions` | `int` | Optional | Dimensions. | | `mask_width` | `int` | Optional | Mask width. | | `mask_height` | `int` | Optional | Mask height. | | `num_classes` | `int` | Optional | Num classes. | ## Predictions | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `label` | `str` | Required | Label. | | `confidence` | `float` | Optional | detection/classification confidence | | `bbox` | `list[int]` | Optional | \[x_min, y_min, x_max, y_max] in input or mask coordinates. | | `coverage_ratio` | `float` | Optional | Fraction of pixels assigned to the class. | ## Generation settings | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `temperature` | `float` | Optional | Temperature. | | `top_p` | `float` | Optional | Top p. | | `top_k` | `int` | Optional | Top k. | | `max_tokens` | `int` | Optional | Max tokens. | | `repetition_penalty` | `float` | Optional | Repetition penalty. | | `frequency_penalty` | `float` | Optional | Frequency penalty. | | `presence_penalty` | `float` | Optional | Presence penalty. | | `seed` | `int` | Optional | Seed. | | `stop_sequences_count` | `int` | Optional | Stop sequences count. | ## Hardware snapshot | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `thermal` | `ThermalContextSchema` | Optional | Nested payload. See the corresponding table. | | `battery_level` | `float` | Optional | Fraction from 0 to 1. | | `battery_charging` | `bool` | Optional | Battery charging. | | `memory_available_bytes` | `int` | Optional | Bytes. | | `cpu_freq_mhz` | `int` | Optional | MHz. | | `cpu_freq_max_mhz` | `int` | Optional | MHz. | | `accelerator_actual` | `str` | Optional | Reported execution target. Not a chipset identifier or proof of a fallback. | ## Thermal snapshot | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `state` | `str` | Optional | nominal|fair|serious|critical | | `state_raw` | `str` | Optional | platform-native value | | `cpu_temp_celsius` | `float` | Optional | Degrees Celsius. | ## Provider metadata | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `resolved_model_id` | `str` | Optional | Resolved model id. | | `system_fingerprint` | `str` | Optional | System fingerprint. | | `service_tier` | `str` | Optional | Service tier. | | `requested_model_id` | `str` | Optional | Requested model id. | ## Model download | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `source_url` | `str` | Required | Download source. URLs may contain application-supplied content. | | `source_type` | `str` | Required | huggingface|s3|gcs|azure|cdn|local_server | | `file_size_bytes` | `int` | Required | Bytes. | | `downloaded_bytes` | `int` | Required | Bytes. | | `duration_ms` | `int` | Required | Elapsed time in milliseconds. | | `bandwidth_bps` | `int` | Optional | Transfer rate in bits per second. | | `network_type` | `str` | Required | wifi|cellular|ethernet|unknown | | `network_generation` | `str` | Optional | Network generation. | | `resumed` | `bool` | Required | Resumed. | | `resume_offset_bytes` | `int` | Optional | Bytes. | | `retry_count` | `int` | Optional | Retry count. | | `cache_hit` | `bool` | Required | Cache hit. | | `checksum_verified` | `bool` | Optional | Checksum verified. | | `checksum_algorithm` | `str` | Optional | Checksum algorithm. | | `decompression_time_ms` | `int` | Optional | Milliseconds. | | `storage_type` | `str` | Optional | Storage type. | | `storage_available_bytes` | `int` | Optional | Bytes. | | `http_status` | `int` | Optional | Http status. | | `cdn_edge` | `str` | Optional | Cdn edge. | | `success` | `bool` | Required | Outcome reported by the producer. | | `error_code` | `str` | Optional | Error code. | | `adapter` | `AdapterDownloadSchema` | Optional | Nested payload. See the corresponding table. | ## Download adapter | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `adapter_id` | `str` | Required | Adapter id. | | `adapter_type` | `str` | Required | lora|qlora|ia3|prefix|full_finetune | | `for_base_model` | `str` | Required | For base model. | | `rank` | `int` | Optional | Rank. | ## Model load | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `duration_ms` | `int` | Required | Elapsed time in milliseconds. | | `memory_bytes` | `int` | Optional | Bytes. | | `peak_memory_bytes` | `int` | Optional | Bytes. | | `memory_mapped` | `bool` | Optional | Memory mapped. | | `accelerator` | `str` | Required | Requested execution target. | | `gpu_layers` | `int` | Optional | Gpu layers. | | `threads` | `int` | Optional | Threads. | | `context_length` | `int` | Optional | Context length. | | `kv_cache_bytes` | `int` | Optional | Bytes. | | `kv_cache_quantization` | `str` | Optional | Kv cache quantization. | | `flash_attention` | `bool` | Optional | Flash attention. | | `rope_scaling` | `str` | Optional | Rope scaling. | | `cold_start` | `bool` | Optional | Cold start. | | `compile_time_ms` | `int` | Optional | Milliseconds. | | `adapter` | `AdapterLoadSchema` | Optional | Nested payload. See the corresponding table. | | `success` | `bool` | Required | Outcome reported by the producer. | | `error_code` | `str` | Optional | Error code. | ## Load adapter | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `adapter_id` | `str` | Required | Adapter id. | | `adapter_type` | `str` | Required | Adapter type. | | `adapter_source` | `str` | Optional | Adapter source. | | `size_bytes` | `int` | Optional | Bytes. | | `rank` | `int` | Optional | Rank. | | `alpha` | `int` | Optional | Alpha. | | `target_modules` | `list[str]` | Optional | Target modules. | | `load_duration_ms` | `int` | Optional | Milliseconds. | ## Model unload | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `duration_ms` | `int` | Required | Elapsed time in milliseconds. | | `reason` | `str` | Required | explicit|memory_pressure|app_background|session_end|thermal | | `memory_freed_bytes` | `int` | Optional | Bytes. | | `peak_memory_bytes` | `int` | Optional | Bytes. | | `uptime_ms` | `int` | Optional | how long the model was loaded | ## Feedback | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `related_inference_id` | `str` | Required | Related inference id. | | `feedback_type` | `str` | Required | accept|reject|undo|edit|thumbs_up|thumbs_down|report | | `delay_ms` | `int` | Optional | Milliseconds. | | `edit_distance` | `int` | Optional | Edit distance. | ## Error | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `error_code` | `str` | Required | Error code. | | `error_message` | `str` | Optional | Optional text. May contain application or provider content. | | `stack_trace_hash` | `str` | Optional | Stack trace hash. | | `related_event_id` | `str` | Optional | Related event id. | | `http_status` | `int` | Optional | Http status. | | `provider_error_code` | `str` | Optional | e.g. insufficient_quota | | `duration_ms` | `int` | Optional | Elapsed time in milliseconds. | ## Span | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `kind` | `str` | Required | agent_step|tool|retrieval|memory|router|guardrail|cache|eval|custom | | `name` | `str` | Required | Name. | | `duration_ms` | `int` | Required | Elapsed time in milliseconds. | | `status` | `str` | Required | ok|error | | `input_summary` | `str` | Optional | Optional content preview. Rejected if it exceeds the configured length limit. | | `output_summary` | `str` | Optional | Optional content preview. Rejected if it exceeds the configured length limit. | | `attributes` | `object` | Optional | Flat scalar map. Nested objects and arrays are rejected. Event and span attributes share a configured size limit. | ## Attachment reference | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `attachment_id` | `str` | Required | Attachment id. | | `role` | `str` | Required | input|output | | `content_type` | `str` | Required | Content type. | ## Telemetry source | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `source` | `string enum` | Required | Source. | | `mapping_version` | `str` | Optional | Mapping version. | | `emitter_version` | `str` | Optional | Emitter version. | ## Service identity | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `name` | `str` | Optional | Name. | | `namespace` | `str` | Optional | Namespace. | | `instance_id` | `str` | Optional | Instance id. | | `deployment_environment` | `str` | Optional | Deployment environment. | | `cloud_region` | `str` | Optional | Cloud region. | ## Reported cost | Field | Type | Presence | Meaning or unit | | --- | --- | --- | --- | | `amount` | `str` | Required | Nonnegative decimal text. Up to 10 integral and 10 fractional digits. | | `currency` | `str` | Required | Three uppercase letters, for example USD. | | `source` | `str` | Required | Source. | | `scope` | `string enum` | Required | attempt or request. Must match the span role. | | `is_estimated` | `bool` | Optional | Is estimated. | ## Content and identifiers Input measurements such as token count, image size, or brightness are metadata. Labels, URLs, errors, attributes, summaries, custom JSON, and attachments can contain content. Do not treat telemetry as inherently free of personal or application data. Attachments upload separately. Events carry their references, not file bytes. See [Captured content](/what-we-collect#captured-content) for collection controls. Device identity behavior varies by SDK and version. Do not infer a universal hashing or cross-project isolation guarantee from the `device_id` field definition. ## Source and scope These tables were checked against the [server ingest schema](https://github.com/wild-edge/wild-edge/blob/main/ingest/schemas.py) on October 30, 2026. They cover accepted payload fields, not an automatic collection matrix or a guarantee of query availability for every field. Server configuration controls size limits. SDK and gateway guides document producer behavior. --- --- url: https://docs.wildedge.dev/what-we-collect.md description: >- Choose telemetry for investigating failures, latency, cost, device issues, and model changes. --- # Troubleshooting guide Use this page to identify which telemetry can help explain a problem. See [Telemetry reference](/telemetry) for event and field definitions and [Integration coverage](/integration-coverage) for collection behavior. Open **Events** in your project or [connect your AI agent](/connect-agent) to inspect it. Field availability depends on the SDK, integration, runtime, and provider. The fields below describe supported signals, not a guarantee that every event contains them. A missing value means unknown, not zero. ## Start with the symptom | Problem | Inspect | | --- | --- | | Calls fail or time out | [Failures](#failures) | | Responses are slow | [Latency](#latency) | | Token use or cost increases | [Usage and cost](#usage-and-cost) | | Only some devices struggle | [Device performance](#device-performance) | | Results change after a release | [Model behavior](#model-behavior) | | A multi-step run fails | [Runs and traces](#runs-and-traces) | | You need the original example | [Captured content](#captured-content) | ## Failures **Applies to:** OpenAI and Anthropic SDK integrations, LiteLLM, OpenRouter, and Bifrost. Start with the failed inference or error event. Compare the error code, model, and elapsed time before opening the surrounding run. | Signal | Use it to check | | --- | --- | | `success`, `error_code` | Which calls failed and how failures are classified | | `http_status`, `provider_error_code` | Whether a remote provider rejected the request | | `duration_ms` | Whether failure was immediate or followed a long wait | | `error_message`, `stack_trace_hash` | Error details and repeated failures, when supplied | | `related_event_id` | The event linked to an SDK error | SDK integrations can report inference failures and separate error events. Gateways report the failures they export. For example, OpenRouter does not export requests rejected before routing. See [gateway limitations](/llm-gateways). Error text can contain content from your code or a provider. Review what your integration sends before treating error messages as content-free telemetry. ## Latency **Applies to:** llama.cpp, MLX, Transformers, remote model APIs, and gateway calls. Separate total call duration from the delay before output starts. For local models, inspect load time and hardware state as well. | Signal | Use it to check | | --- | --- | | `duration_ms` | Total inference duration | | `time_to_first_token_ms` | Delay before generation starts | | `tokens_out`, `tokens_per_second` | Output size and generation throughput | | `model_load` duration | Model startup overhead | | Span durations | Time spent in tools, retrieval, or other application work | SDK integrations supply timing supported by the runtime or provider. Gateways supply exported call timing. OpenRouter reports time to first token for streamed and non-streamed calls. Compare calls with similar models, input sizes, and output sizes. Longer output can increase total duration without indicating slower generation. ## Usage and cost **Applies to:** LiteLLM, OpenRouter, and Bifrost for reported cost. SDK integrations can supply token usage. Compare usage by requested model and the model that served the call. Check missing prices before interpreting totals. | Signal | Use it to check | | --- | --- | | `tokens_in`, `tokens_out` | Input and output token use | | `cached_input_tokens`, `reasoning_tokens_out` | Cached input and reasoning usage, when reported | | `requested_model_id`, `model_name`, `model_provider` | Gateway routing and model selection | | `reported_cost_amount`, `reported_cost_currency` | Gateway-reported cost | | `reported_cost_is_estimated` | Whether that cost is an estimate | | `request_id` | Related gateway attempts, where supported | The cost fields above come from gateway exports. LiteLLM and Bifrost report estimated prices. OpenRouter reports the amount charged. Missing cost does not mean a free call. [Gateway fields and query examples](/llm-gateways#query-gateway-events) cover these differences. If the gateway exports a cloud call, disable SDK tracking for that call to avoid counting it twice. SDK tracking for on-device models and gateway tracking for cloud models do not overlap. See [app and gateway setup](/setup/sdk-and-gateway). ## Device performance **Applies to:** Core ML, TensorFlow Lite, ONNX Runtime, and other SDK-tracked local runtimes. Compare device models first. Accelerator values identify execution targets such as CPU or GPU. They do not necessarily identify a chipset or prove that its NPU was used. Filter by device, app version, and model version. Compare affected devices with devices running the same model successfully. | Signal | Use it to check | | --- | --- | | Device model, OS version, app version | Whether the issue is limited to a device class or release | | Thermal state and CPU frequency | Whether heat or throttling coincides with slower calls | | Available memory | Whether memory pressure coincides with failures | | `accelerator_actual` | Which accelerator ran the inference | | Model load and unload events | Startup overhead and model eviction | | Requested and actual accelerator | Differences between configuration and reported execution | These signals require SDK instrumentation and platform support. Gateway exports do not describe the calling device's hardware. A missing accelerator value does not prove the requested accelerator was used. ## Model behavior **Applies to:** ONNX Runtime, Transformers, Core ML, and other integrations that supply model and prediction metadata. Compare the same task across model versions, app releases, runtimes, and device classes. Use feedback and captured examples to assess whether a change improved results. | Signal | Use it to check | | --- | --- | | Model name, version, format, quantization | Which model configuration changed | | `resolved_model_id`, `system_fingerprint`, `service_tier` | Provider metadata returned for an SDK-tracked API call | | Classification labels, confidence, bounding boxes | Changes in predictions, where supplied | | Image brightness, audio quality, text length and language | Changes in input measurements, where supplied | | Generation settings and stop reason | Changes in generation configuration or completion behavior | | Feedback linked to an inference | User acceptance, rejection, or edits | SDK support varies by integration. Some values require manual tracking. Gateway exports provide call metadata and usage, not the same prediction, input-quality, or feedback signals as SDK instrumentation. Confidence and input statistics help locate changes. They do not establish whether a prediction was correct. Inspect feedback or examples before drawing that conclusion. ## Runs and traces Start with one failed or slow event, then follow its run or trace to inspect preceding steps. | Signal | Use it to check | | --- | --- | | `trace_id`, `span_id`, `parent_span_id` | Parent and child relationships | | `run_id`, `agent_id` | Events associated with an agent run | | Span name, kind, duration, status | Which application step failed or took time | | `conversation_id`, `step_index` | Conversation or execution position, when supplied | SDK correlation depends on the instrumentation and context passed between steps. SDK and gateway events are not automatically linked into one trace. [Investigate events and traces](/investigate) provides prompts for a first investigation. ## Captured content Measurements can identify a problem without showing the original input or output. To inspect an example, check whether content was explicitly supplied or capture was enabled for that integration. | Content | How it reaches WildEdge | | --- | --- | | Input or output files | Attachments uploaded separately and referenced by an inference event | | Span input and output previews | Optional `input_summary` and `output_summary` | | Custom context | Values supplied in `attributes` | | Error details | Error messages supplied by your code or integration | Input and output capture is opt-in. Follow your SDK guide to configure capture or supply attachments. Support and upload limits depend on the integration and project configuration. WildEdge keeps prompt and response text from gateway traces as event summaries, when the gateway exports it. LiteLLM leaves it out by default, Bifrost with `disable_content_logging`, and OpenRouter in Privacy Mode. Review summaries, attributes, error messages, and attachments for sensitive content. Disabling attachments does not remove content supplied in other fields. ## Missing events or fields 1. Confirm that events are going to the intended project. 2. Check that your SDK integration or gateway exports the signal you need. 3. Run one inference and find its event before expanding the time range. 4. Check exporter or SDK logs if the event does not arrive. Follow [app setup](/setup/sdk) or [gateway troubleshooting](/llm-gateways#troubleshooting) for connection checks. Use the [API reference](https://app.wildedge.dev/api/docs) for endpoint schemas. ## Next * [Investigate events and traces](/investigate) with these fields. * [Telemetry reference](/telemetry): every field, type, and unit.