# Hud SDK Installation Guide Documentation

## Guides
- [Hud MCP in Cursor Automations](https://docs.hud.io/docs/hud-mcp-in-cursor-automations.md): Build Production-Aware Developer Workflows
- [Hud MCP Server Overview](https://docs.hud.io/docs/hud-mcp-server.md)
- [Start Using Hud MCP Server](https://docs.hud.io/docs/install-mcp.md): Power up your AI with real-time production context using Hud MCP Server
- [Troubleshooting MCP Errors](https://docs.hud.io/docs/troubleshooting-mcp-errors.md): The MCP comes bundled with our IDE extension and leverages the extension's authentication. It may occasionally encounter issues either due to internal errors or due to agent-related failures in executing it. This guide outlines how to reload the MCP and how to respond to common error messages
- [IDE Extension Features](https://docs.hud.io/docs/ide-extension-features.md)
- [Install Hud in Cursor](https://docs.hud.io/docs/install-hud-in-cursor.md): This guide walks you through setting up the Hud extension on the Cursor IDE, so you can start using Hud instantly in your development workflow.
- [Install Hud in VSCode](https://docs.hud.io/docs/install-ide-extension.md): This guide walks you through setting up the Hud extension on the VS Code IDE, so you can start using Hud instantly in your development workflow.
- [Install Hud in JetBrains](https://docs.hud.io/docs/jetbrains-extension.md): This guide walks you through setting up the Hud extension on JetBrains IDE, so you can start using Hud instantly in your development workflow.
- [Heads-Up Alerts](https://docs.hud.io/docs/heads-up-alerts.md)
- [Slack Integration of Heads-up Alerts](https://docs.hud.io/docs/slack-integration-alerts.md): Get instant visibility into issues and their root causes. Hud helps your team respond faster by sending real-time alerts and code-level context straight into your Slack channels.
- [HudQL API](https://docs.hud.io/docs/hudql-api.md): Use Hud's API for flexible access to your runtime data: build automations, dashboards, and alerts, or give your AI coding agent direct SQL access to production behavior.
- [Use Hud in CI/CD for PR Comparison](https://docs.hud.io/docs/introducing-hud-pr-comparison.md)
- [Quick Start Guide](https://docs.hud.io/docs/installation-guide.md)
- [Welcome to Hud](https://docs.hud.io/docs/welcome.md)
- [What You Can Do with Hud](https://docs.hud.io/docs/what-you-can-do-with-hud.md)
- [Compatibility Matrix for Python](https://docs.hud.io/docs/hud-sdk-compatibility-matrix-for-python.md): This document outlines the system requirements and development environment compatibility for using the Hud SDK with Python. Use this guide to ensure your local development environment is properly set up to support the SDK’s functionality and integrations.
- [Python Installation](https://docs.hud.io/docs/hud-python-installation.md): Integrate Hud Python SDK for enhanced observability in your application in a few simple steps
- [Mark a Flow as Failed Python](https://docs.hud.io/docs/mark-a-flow-as-failed-python.md): Manually flag an HTTP or queue flow as failed when no exception was raised or auto-detected
- [Troubleshooting SDK Errors](https://docs.hud.io/docs/py-sdk-ie.md): A list of all Python SDK runtime errors, their causes, and how to fix them.
- [Setting Custom Context for Requests for Python](https://docs.hud.io/docs/setting-custom-context-for-requests-python.md): Set per-request context to surface important metadata when things go wrong.
- [Compatibility Matrix for Node.js](https://docs.hud.io/docs/hud-sdk-compatibility-matrix-for-node.md): Supported Node.js environments and setup requirements for the Hud SDK.
- [Import Hud as Early as Possible](https://docs.hud.io/docs/import-hud-as-early-as-possible.md): To ensure Hud can track **all of your code**, including your **HTTP and queue frameworks**, it's critical to initialize it **before any of your application code loads**.
- [Node.js Installation](https://docs.hud.io/docs/nodejs-installation-guide.md): Integrate Hud Node.js SDK for enhanced observability in your application in a few simple steps
- [Troubleshooting SDK Errors](https://docs.hud.io/docs/node-sdk-ie.md): A list of all Node.js SDK runtime errors, their causes, and how to fix them.
- [Setting Custom Context for Requests for Nodejs](https://docs.hud.io/docs/setting-custom-context-for-requests-nodejs.md): Set per-request context to surface important metadata when things go wrong.
- [FAQ ](https://docs.hud.io/docs/faq.md): Hud helps engineers understand how their code behaves in production - at the function level. This FAQ covers common questions about the integration and product.
- [Understanding P90 Duration](https://docs.hud.io/docs/p90.md)
- [PII Scrubbing and Data Collection in Hud](https://docs.hud.io/docs/pii-scrubbing-and-data-collection-in-hud.md): Hud minimizes PII risk by separating metrics from forensics and scrubbing sensitive data inside your pods before anything is sent out.
- [Support](https://docs.hud.io/docs/support.md): Get help, fast.
- [Release Notes](https://docs.hud.io/docs/web-release-notes.md): Stay updated with the latest improvements and capabilities in Hud's web experience. Observe, analyze, and resolve issues faster with each release.

## API Reference
- [Execute HudQL query](https://docs.hud.io/reference/executequery.md): Execute HudQL query.  **Request:** - `query` (required): SQL query to execute. - `environment` (optional): Environment name (e.g., production, staging) to scope the query. defaults to all environments. - `service_names` (optional): Service names to scope the query. defaults to all services.  **Response:** The response format depends on the `Accept` header: - `application/json` (default): JSON, { result: Record<string, unknown>[] } - `text/csv`: CSV string with column headers  # Database Schema  **Session Context** Common columns used by multiple tables. Columns: - `session_id` (String): Session identifier - `session_tags` (Map(String, String)): Custom tags attached to the session - `pod_name` (String): Pod or runtime instance name  **Service Context** Common columns used by multiple tables. Columns: - `service_name` (String): Service name - `service_id` (UInt32): Service identifier - `environment_name` (String): Environment name such as production or staging  **Metric Aggregates** Common aggregated metric columns used by function and endpoint metrics tables. Columns: - `invocations` (UInt64): Number of invocations in the aggregation period - `total_duration_ms` (Float64): Total execution time in milliseconds - `total_squared_duration_ms` (Float64): Sum of squared durations for variance or standard deviation calculations - `duration_buckets` (AggregateFunction): Pre-aggregated duration quantiles, use `percentileMS(duration_buckets, percentile)` - `exceptions` (Map(String, Float64)): Exception or error counts grouped by type  **Table: FunctionMetricsHighResolution** Description: Minutes-level function metrics by session. Use for small time windows. Columns: - Session Context: Shared session columns - Service Context: Shared service columns - `service_runtime` (String): Service runtime such as NODEJS, PYTHON, or JAVA - `timestamp_end` (DateTime): End of the metric period - `function_id` (UInt32): Function identifier - `caller_function_id` (UInt32): Calling function identifier, or 0 if none - `wrapped_endpoint_id` (UInt32): Endpoint this function is called within - Metric Aggregates: Shared aggregated metric columns  **Table: FunctionMetricsLowResolution** Description: Hourly aggregated function metrics across sessions. Use for historical trends. Columns: - `hour_end` (DateTime): Hour bucket timestamp - `function_id` (UInt32): Function identifier - `caller_function_id` (UInt32): Calling function identifier - `wrapped_endpoint_id` (UInt32): Endpoint this function is called within - Service Context: Shared service columns - `service_runtime` (String): Service runtime such as NODEJS, PYTHON, or JAVA - Metric Aggregates: Shared aggregated metric columns - `session_tags` (Map(String, String)): Session tags for this aggregation  **Table: EndpointMetricsHighResolution** Description: Minutes-level endpoint metrics by session for HTTP, Kafka, SQS, GraphQL, and similar endpoint types. Columns: - Session Context: Shared session columns - Service Context: Shared service columns - `service_runtime` (String): Service runtime such as NODEJS, PYTHON, or JAVA - `timestamp_end` (DateTime): End of the metric period - `endpoint_id` (UInt32): Endpoint identifier - `endpoint_type` (String): Endpoint type such as HTTP, KAFKA, SQS, GRAPHQL, or ARQ - `msg_count` (UInt64): Message count for queue-based endpoints - `status_codes` (Map(String, Float64)): HTTP status code distribution - Metric Aggregates: Shared aggregated metric columns - `total_e2e_duration_ms` (Float64): Total end-to-end duration for queue endpoints - `total_squared_e2e_duration_ms` (Float64): Sum of squared end-to-end durations - `e2e_duration_buckets` (AggregateFunction): Pre-aggregated end-to-end duration quantiles - `fingerprints` (Map(String, UInt64)): Error fingerprints with counts  **Table: EndpointMetricsLowResolution** Description: Hourly aggregated endpoint metrics. Use for historical analysis and capacity planning. Columns: - `hour_end` (DateTime): Hour bucket timestamp - Service Context: Shared service columns - `service_runtime` (String): Service runtime such as NODEJS, PYTHON, or JAVA - `endpoint_id` (UInt32): Endpoint identifier - `endpoint_type` (String): Endpoint type such as HTTP, KAFKA, SQS, GRAPHQL, or ARQ - `msg_count` (UInt64): Message count - `status_codes` (Map(String, Float64)): HTTP status code distribution - Metric Aggregates: Shared aggregated metric columns - `total_e2e_duration_ms` (Float64): Total end-to-end duration for queue endpoints - `total_squared_e2e_duration_ms` (Float64): Sum of squared end-to-end durations - `e2e_duration_buckets` (AggregateFunction): Pre-aggregated end-to-end duration quantiles - `session_tags` (Map(String, String)): Session tags for this aggregation - `fingerprints` (Map(String, UInt64)): Error fingerprints with counts  **Table: Functions** Description: Function metadata table used to map function IDs to readable names and source locations. Columns: - `function_id` (UInt32): Function identifier - `function_signature` (String): Human-readable function signature - `file` (String): Source file path - `line_number` (UInt32, Nullable): Starting line number in the source file - `is_async` (Boolean): Whether the function is async - `third_party` (String): Third-party module name, empty if not third party - `services`  - _unstable_ - (Array(Tuple(UInt32, String))): Service IDs and service names where the function appears  **Table: Endpoints** Description: Endpoint metadata table that maps endpoint IDs to routing or queue information. Columns: - `endpoint_id` (UInt32): Endpoint identifier - `type` (String): Endpoint type such as HTTP, KAFKA, SQS, GRAPHQL, or ARQ - `endpoint_name` (String): Unified endpoint name such as an HTTP path or queue name - `http_methods` (Array(String)): HTTP methods for HTTP endpoints - `services`  - _unstable_ - (Array(Tuple(UInt32, String))): Service IDs and service names where the endpoint appears  **Table: FunctionDeployments - _unstable_** Description: Function deployment timestamps by service and environment. Columns: - Service Context: Shared service columns - `function_id` (UInt64): Function identifier - `deployment_timestamp` (DateTime): Deployment timestamp  **Table: EndpointDeployments - _unstable_** Description: Endpoint deployment timestamps by service and environment. Columns: - Service Context: Shared service columns - `endpoint_id` (UInt32): Endpoint identifier - `deployment_timestamp` (DateTime): Deployment timestamp  **Table: MachineMetrics** Description: Infrastructure metrics per session for CPU, memory, and event loop utilization. Columns: - Session Context: Shared session columns - `service_name` (String): Service name - `environment_name` (String): Environment name - `service_runtime` (String): Service runtime such as NODEJS, PYTHON, or JAVA - `timestamp` (DateTime): Metric timestamp - `pid` (UInt32): Process ID - `owner` (String): Metric owner such as Process or MainThread - `uptime_seconds` (Float64): Process uptime in seconds - `memory_rss_bytes` (UInt64): Resident set size - `memory_utilization_percentage` (Float64): Memory usage percentage - `event_loop_utilization_percentage` (Float64): Node.js event loop utilization percentage, or -1 if not applicable - `cpu_usage_percentage` (Float64): CPU usage percentage, or -1 if not applicable - `cpu_user_time` (Float64): CPU user time in seconds - `cpu_system_time` (Float64): CPU system time in seconds  **Table: Forensics** Description: Sampled execution traces for debugging slow requests or errors. Columns: - `timestamp_start` (DateTime): Request start time - `endpoint_id` (UInt32): Endpoint that initiated the flow - Service Context: Shared service columns - Session Context: Shared session columns - `trigger_type` (String): Trace trigger type such as Error or Duration - `duration_ms` (Float64): Total flow duration in milliseconds - `functions` (Array(UInt32)): Function IDs in execution order - `exceptions` - _unstable_ - (Array(String)): Exception messages - `exceptions_data_enriched` - _unstable_ - (Array(Tuple(String, Array(UInt32)))): Exception messages enriched with function IDs - `fingerprint` (String): Identifier used to group similar errors - `failure_type` - _unstable_ - (String): Failure type for queue endpoints - `caught` - _unstable_ - (Bool): Whether the exception was caught - `forensic_id` - _unstable_ - (String): Unique investigation identifier
- [Get issue details](https://docs.hud.io/reference/getissue.md): Retrieve detailed information about a specific issue by its ID.  **Response includes:** - Full issue details (type, title, summary, timestamps) - Affected entity information - Source functions  **Example:** `GET /issues/12345`
- [List issues](https://docs.hud.io/reference/listissues.md): Retrieve a paginated list of issues detected by Hud.  **Filtering Options:** - Filter by environment (default: production) - Filter by service ID(s) or service name(s) - Filter by time range (relative like "7d" or explicit ISO 8601 timestamps) - Filter by custom tags  **Response:** Returns an array of issues with pagination metadata. Each issue includes: - Issue details (id, type, title, summary) - Timing information (first_seen_at, last_seen_at) - Affected entity details (endpoint, queue, or function) - Source function  **Example:** `GET /issues?relative_time_frame=7d&service_name=payment-service&limit=10`

## Changelog
- [User-Defined Errors — Complete Error Coverage Beyond 5xx](https://docs.hud.io/changelog/user-defined-errors-complete-error-coverage-beyond-5xx.md)
- [Issue Detection for Multiple Environments](https://docs.hud.io/changelog/issue-detection-for-multiple-environments.md)
- [SLO Issues – Now investigable & configurable](https://docs.hud.io/changelog/slo-issues-now-investigable-configurable.md)
- [Service Usage Visibility and Control](https://docs.hud.io/changelog/service-usage-visibility-and-control.md)
- [Prompt to Fix for Every Issue — From Detection to Fix in One Click](https://docs.hud.io/changelog/prompt-to-fix-for-every-issue-from-detection-to-fix-in-one-click.md)