# Hud SDK Installation Guide Documentation

> Documentation for Hud SDK Installation Guide

## Guides
- [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)
- [Quick Start Guide](https://docs.hud.io/docs/installation-guide.md)
- [Hud MCP Server Overview](https://docs.hud.io/docs/hud-mcp-server.md)
- [Hud MCP in Cursor Automations](https://docs.hud.io/docs/hud-mcp-in-cursor-automations.md): Build Production-Aware Developer Workflows
- [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
- [Hud Remote MCP Server](https://docs.hud.io/docs/remote-mcp.md): Connect directly to Hud's hosted MCP server over HTTPS — for cases where the local MCP can't be used.
- [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
- [Agentic Workflows](https://docs.hud.io/docs/agentic-workflows.md): Give your coding agents real production context — automate PR risk checks, health reports, dead-code cleanup, and rollback decisions with Hud runtime data.
- [Quick Start](https://docs.hud.io/docs/agentic-workflows-quick-start.md): Set up your first agentic workflow — a PR blast-radius check on GitHub Actions — in about 10 minutes.
- [Choosing a Runner](https://docs.hud.io/docs/agentic-workflows-runners.md): Compare the four runners — GitHub Actions, gh-aw, Cursor, and Claude routines — and follow step-by-step setup for each.
- [Recipe Catalog](https://docs.hud.io/docs/agentic-workflows-recipes.md): The four ready-made agentic workflows — what each does, its inputs and outputs, and how to configure it.
- [FAQ & Best Practices](https://docs.hud.io/docs/agentic-workflows-faq.md): Common questions, configuration tips, and fixes for Hud agentic workflows.
- [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
- [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.
- [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.
- [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**.
- [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.
- [Mark as Flow (Manual Flows)](https://docs.hud.io/docs/mark-as-flow-nodejs.md): Manually mark code as a flow to track entry points that aren't covered by Hud's automatic instrumentation.
- [Mark a Flow as Failed](https://docs.hud.io/docs/mark-a-flow-as-failed-nodejs.md): Manually flag an HTTP or queue flow as failed when no exception was raised or auto-detected.
- [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
- [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.
- [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.
- [Mark as Flow (Manual Flows)](https://docs.hud.io/docs/mark-as-flow-python.md): Manually mark code as a flow to track entry points that aren't covered by Hud's automatic instrumentation.
- [Mark a Flow as Failed](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.
- [Java Installation](https://docs.hud.io/docs/java-installation.md): Integrate Hud Java Agent for enhanced observability in your application in a few simple steps
- [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.
- [Heads-Up Alerts](https://docs.hud.io/docs/heads-up-alerts.md)
- [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.
- [Use Hud in CI/CD for PR Comparison](https://docs.hud.io/docs/introducing-hud-pr-comparison.md)
- [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.
- [Support](https://docs.hud.io/docs/support.md): Get help, fast.
- [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.
- [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
- [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`
- [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`
- [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

## Changelog
- [Machine Metrics — now alongside your code metrics](https://docs.hud.io/changelog/machine-metrics-now-alongside-your-code-metrics.md)
- [Export Tables to CSV](https://docs.hud.io/changelog/export-tables-to-csv.md)
- [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)