### Setup Development Environment

Source: https://github.com/parca-dev/parca/blob/main/ui/README.md

Run this command on Linux to install all necessary tools for development.

```shell
make dev/setup
```

--------------------------------

### Start Parca Service

Source: https://github.com/parca-dev/parca/blob/main/snap/README.md

Starts the Parca service provided by the snap. This command assumes Parca has already been installed.

```bash
$ snap start parca
```

--------------------------------

### Development Setup Command

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Command to start Parca in development mode, specifying a configuration file, log level, and HTTP address.

```bash
./parca \
  --config-path=parca.yaml \
  --log-level=debug \
  --http-address=localhost:7070

```

--------------------------------

### Production Setup with S3 Configuration

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Example configuration for a production environment using S3 for object storage. Specifies the S3 bucket and region.

```yaml
# parca.yaml
object_storage:
  bucket:
    type: s3
    config:
      bucket: parca-prod
      region: us-east-1

scrape_configs:
  - job_name: prod-services
    scrape_interval: 30s
    static_configs:
      - targets: [...] 

```

--------------------------------

### Install Parca Snap

Source: https://github.com/parca-dev/parca/blob/main/snap/README.md

Installs the Parca snap from the 'edge' channel. This is the first step before running Parca.

```bash
# Install from the 'edge' channel
$ sudo snap install parca --channel edge
```

--------------------------------

### Complete Parca YAML Configuration Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating object storage and scrape configurations in YAML format.

```yaml
object_storage:
  bucket:
    type: s3
    config:
      bucket: my-parca-bucket
      endpoint: s3.amazonaws.com
      access_key: AKIA...
      secret_key: XXXX...

scrape_configs:
  - job_name: "parca"
    scrape_interval: 10s
    scrape_timeout: 15s
    scheme: http
    static_configs:
      - targets: ["localhost:7070"]
    profiling_config:
      pprof_config:
        process_cpu:
          enabled: true
          path: /debug/pprof/profile
          delta: true
          seconds: 10
        memory:
          enabled: true
          path: /debug/pprof/allocs
        goroutine:
          enabled: true
          path: /debug/pprof/goroutine
        block:
          enabled: true
          path: /debug/pprof/block
        mutex:
          enabled: true
          path: /debug/pprof/mutex

  - job_name: "prometheus"
    scrape_interval: 10s
    scrape_timeout: 15s
    scheme: http
    static_configs:
      - targets: ["prometheus:9090"]
    relabel_configs:
      - source_labels: [__address__]
        regex: "([^:]+):[0-9]+"
        target_label: instance
        replacement: "${1}"
```

--------------------------------

### Set Up Local Development Cluster

Source: https://github.com/parca-dev/parca/blob/main/ui/README.md

Initialize a cluster and all other required components for a local development setup.

```shell
make dev/up
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/parca-dev/parca/blob/main/CONTRIBUTING.md

Install pre-commit hooks to automate linting and formatting checks before committing code.

```bash
pre-commit install
```

--------------------------------

### Configure Object Storage (S3 Example)

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/server-components.md

Example configuration for external object storage, specifically for S3. Specifies the bucket name and endpoint.

```yaml
object_storage:
  bucket:
    type: s3
    config:
      bucket: parca-profiles
      endpoint: s3.amazonaws.com
```

--------------------------------

### Download and Run Parca with Custom Config

Source: https://github.com/parca-dev/parca/blob/main/snap/README.md

Downloads the default Parca configuration file and then starts Parca using this downloaded file.

```bash
# Or grab the default config from the Parca repo
$ wget -qO ~/parca.yaml https://raw.githubusercontent.com/parca-dev/parca/main/parca.yaml
$ parca --config-file=~/parca.yaml
```

--------------------------------

### Run Local Development with Tilt

Source: https://github.com/parca-dev/parca/blob/main/ui/README.md

Start the local development environment using Tilt for managing the application stack.

```shell
tilt up
```

--------------------------------

### Start Parca Backend

Source: https://github.com/parca-dev/parca/blob/main/ui/README.md

Run the Parca backend with the --cors-allowed-origins='*' flag to enable CORS headers, allowing the UI to connect.

```shell
./bin/parca --cors-allowed-origins='*'
```

--------------------------------

### Get Agents Response Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON response detailing metadata about agents that have sent profiles, including their IDs, labels, and last profile reception time.

```json
{
  "agents": [
    {
      "id": "parca-agent-0",
      "labels": {
        "labels": [
          {"name": "instance", "value": "localhost:7071"}
        ]
      },
      "last_profile_received": "2024-01-01T12:30:45Z"
    }
  ]
}
```

--------------------------------

### QueryRange HTTP Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/query-service.md

Example of how to use the QueryRange HTTP endpoint to fetch aggregated profile data within a specified time range and step.

```bash
curl -X GET "http://localhost:7070/profiles/query_range?query=job%3D%22parca%22&start=2024-01-01T00:00:00Z&end=2024-01-01T01:00:00Z&step=60s"
```

--------------------------------

### Run Parca with Default Config

Source: https://github.com/parca-dev/parca/blob/main/snap/README.md

Starts the Parca application using the default configuration file located within the snap's data directory.

```bash
# Start Parca with the default config file from the SNAP_DATA directory
$ parca --config-file=/var/snap/parca/current/parca.yaml
```

--------------------------------

### Start Parca Web Development Server

Source: https://github.com/parca-dev/parca/blob/main/ui/README.md

Run the development server for the Parca React app using pnpm with the @parca/web filter.

```shell
pnpm --filter @parca/web dev
```

--------------------------------

### Query API - Top N Functions Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/query-service.md

Use this snippet to query for the top N functions. This is useful for identifying performance bottlenecks.

```bash
curl -X GET "http://localhost:7070/profiles/query?mode=1&single.query=job%3D%22app%22&single.time=2024-01-01T00:30:00Z&report_type=2"
```

--------------------------------

### Get Scrape Targets Response Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON response detailing configured scrape targets and their status, including discovered labels, agent labels, and scrape metrics.

```json
{
  "targets": {
    "parca": {
      "targets": [
        {
          "discovered_labels": {
            "labels": [
              {"name": "__scheme__", "value": "http"},
              {"name": "__address__", "value": "localhost:7070"}
            ]
          },
          "labels": {
            "labels": [
              {"name": "job", "value": "parca"},
              {"name": "instance", "value": "localhost:7070"}
            ]
          },
          "last_error": "",
          "last_scrape": "2024-01-01T12:30:45Z",
          "last_scrape_duration": "250ms",
          "url": "http://localhost:7070/debug/pprof/profile",
          "health": 1
        }
      ]
    }
  }
}
```

--------------------------------

### Initiate Debug Info Upload Response Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON response after initiating a debug info upload, including the upload ID, a signed URL for storage, and upload instructions.

```json
{
  "upload_id": "session-uuid",
  "signed_url": "https://storage.example.com/...",
  "upload_instructions": "POST to signed URL"
}
```

--------------------------------

### Share Profile Response Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Example JSON response when a profile is successfully shared, containing a shareable link.

```json
{
  "link": "https://pprof.me/share/abc123xyz"
}
```

--------------------------------

### Initiate Debug Info Upload Request Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON request body to initiate a debug info upload, providing build ID, hash, and type information.

```json
{
  "build_id": "abcd1234",
  "hash": "sha256:abc123...",
  "type": 0,
  "build_id_type": 1
}
```

--------------------------------

### Check Debug Info Upload Initiation Response Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON response indicating whether a debug info upload should be initiated and the reason for the decision.

```json
{
  "should_initiate_upload": true,
  "reason": "build_id not cached"
}
```

--------------------------------

### GET /

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Serves the web UI. This endpoint returns an HTML page for the user interface.

```APIDOC
## GET /

### Description
Serves the web UI.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
HTML page

#### Status Codes
- 200 OK: UI returned
- 404 Not Found: UI files missing
```

--------------------------------

### Example Full Endpoint with Path Prefix

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

This shows how a full endpoint URL is constructed when a path prefix is configured. Ensure your client uses this full URL for requests.

```http
GET http://localhost:7070/parca/profiles/query
```

--------------------------------

### Go Duration Format Examples

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/README.md

Shows the standard Go duration format for specifying time intervals in Parca.

```plaintext
10s     # 10 seconds
5m      # 5 minutes
1h      # 1 hour
```

--------------------------------

### Configure OTLP HTTP Exporter

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Configure the OTLP exporter to use HTTP. Example sets the address to localhost:4318.

```bash
./parca --otlp-address=http://localhost:4318 --otlp-exporter=http
```

--------------------------------

### Parca Query Language Examples

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/README.md

Demonstrates the syntax for Parca's label-based query language, similar to Prometheus.

```plaintext
{job="parca", instance=~"localhost.*"}
{job!="test", region="us-east-1"}
```

--------------------------------

### ProfileTypes API - Response Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/query-service.md

This is an example of the JSON response structure when querying the ProfileTypes endpoint, showing available profile details.

```json
{
  "types": [
    {
      "name": "cpu",
      "sample_type": "samples",
      "sample_unit": "count",
      "period_type": "time",
      "period_unit": "nanoseconds",
      "delta": false
    },
    {
      "name": "memory",
      "sample_type": "bytes",
      "sample_unit": "byte",
      "period_type": "bytes",
      "period_unit": "byte",
      "delta": false
    }
  ]
}
```

--------------------------------

### Relabeling Configuration Examples

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Demonstrates various relabeling rules for manipulating labels during service discovery. Includes extracting hostnames, dropping targets, renaming labels, and adding static labels.

```yaml
relabel_configs:
  # Extract hostname from address
  - source_labels: [__address__]
    regex: "([^:]+)"
    target_label: hostname
  
  # Drop targets with skip_profiling=true label
  - source_labels: [__meta_kubernetes_pod_label_skip_profiling]
    regex: "true"
    action: drop
  
  # Rename __meta_kubernetes_pod_name to pod
  - source_labels: [__meta_kubernetes_pod_name]
    target_label: pod
  
  # Add static label
  - target_label: datacenter
    replacement: us-east-1

```

--------------------------------

### Run Compiled Parca Binary

Source: https://github.com/parca-dev/parca/blob/main/README.md

Execute the compiled Parca binary located at 'bin/parca'. This will start the Parca service, making its web UI available on http://localhost:7070/.

```bash
./bin/parca
```

--------------------------------

### Check Debug Info Upload Initiation Request Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON request body to check if a debug info upload should be initiated, specifying build ID, hash, and other parameters.

```json
{
  "build_id": "abcd1234",
  "hash": "sha256:abc123...",
  "force": false,
  "type": 0,
  "build_id_type": 1
}
```

--------------------------------

### Set Active Storage Memory

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Allocate memory for active profile storage. Example sets it to 1GB.

```bash
./parca --storage-active-memory=1073741824 # 1GB
```

--------------------------------

### Startup Error: Port Permission Denied

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

This error message indicates that the HTTP server cannot start because it lacks the necessary permissions to bind to the specified port (e.g., port 80).

```text
Error starting HTTP server: listen tcp :80: bind: permission denied
```

--------------------------------

### GET /ready

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Readiness probe endpoint. This endpoint can be used to check if the server is ready to handle requests, returning a simple OK response.

```APIDOC
## GET /ready

### Description
Readiness probe endpoint (if configured).

### Method
GET

### Endpoint
/ready

### Response
#### Success Response (200)
Simple OK response

#### Status Codes
- 200 OK: Server ready
- 503 Service Unavailable: Server not ready
```

--------------------------------

### Configure OTLP Exporter

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Set the OTLP exporter endpoint and type. Example configures gRPC on localhost:4317.

```bash
./parca --otlp-address=localhost:4317 --otlp-exporter=grpc
```

--------------------------------

### Build Parca UI Production

Source: https://github.com/parca-dev/parca/blob/main/ui/README.md

Generate a production build of the React app using the Makefile. This command also handles pnpm installation and building.

```shell
make ui/build # pnpm install && pnpm build
```

--------------------------------

### Initiate Upload Response

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/debuginfo-service.md

Example response when initiating an upload. It includes a unique upload ID and a signed URL for direct object storage uploads.

```json
{
  "upload_id": "upload-session-uuid",
  "signed_url": "https://storage.example.com/upload?token=xyz...",
  "upload_instructions": "POST debug info to signed URL"
}
```

--------------------------------

### Example: Profile Not Found Error

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

Shows a 'NOT_FOUND' error indicating no profiles match the query or the specified time range. Verify label values using the /labels endpoints.

```text
query: {job="nonexistent"}
error: NOT_FOUND: no profiles found for query
```

--------------------------------

### Initiate Upload Request

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/debuginfo-service.md

Initiates an upload session for debug information by providing the build ID, hash, and type. Use this to get an upload ID and a signed URL if applicable.

```bash
curl -X POST http://localhost:7070/initiateupload \
  -H "Content-Type: application/json" \
  -d '{
    "build_id": "abcd1234",
    "hash": "sha256:abc123...",
    "type": 1,
    "build_id_type": 1
  }'
```

--------------------------------

### Run Parca with OTLP Address

Source: https://github.com/parca-dev/parca/blob/main/scripts/local-tracing/README.md

Start the Parca binary with the OpenTelemetry Protocol (OTLP) address flag to send traces to the local OpenTelemetry collector.

```bash
./bin/parca --otlp-address=127.0.0.1:4317
```

--------------------------------

### GET /static/*

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Serves static assets such as CSS, JavaScript, and images. This endpoint is used to deliver static files required by the UI.

```APIDOC
## GET /static/*

### Description
Serves static assets (CSS, JavaScript, images).

### Method
GET

### Endpoint
/static/*

### Response
#### Status Codes
- 200 OK: Asset served
- 304 Not Modified: Browser cached version
- 404 Not Found: Asset not found
```

--------------------------------

### Configure Scraper Jobs

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/server-components.md

Example configuration for scrape jobs, defining targets and profiling settings. Includes job name, scrape interval, and pprof configuration.

```yaml
scrape_configs:
  - job_name: myapp
    scrape_interval: 10s
    static_configs:
      - targets: ["localhost:6060"]
    profiling_config:
      pprof_config:
        cpu:
          enabled: true
          path: /debug/pprof/profile
```

--------------------------------

### Static Target Discovery Configuration

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/scrape-service.md

Example of configuring static targets in parca.yaml, specifying a list of hosts and ports to scrape, along with custom labels.

```yaml
scrape_configs:
  - job_name: "static"
    static_configs:
      - targets: ["host1:6060", "host2:6060"]
        labels:
          region: us-east-1

```

--------------------------------

### Upload Debug Info Response Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON response after successfully streaming debug info files, containing an upload ID for the session.

```json
{
  "upload_id": "upload-session-uuid"
}
```

--------------------------------

### Get All Targets (HTTP)

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/scrape-service.md

Retrieves all scrape targets configured in Parca using an HTTP GET request. No specific setup is required beyond having the service running.

```bash
curl -X GET "http://localhost:7070/targets"
```

--------------------------------

### Set Debug Info Upload Max Size

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Set the maximum size for debug info uploads. Example sets it to 2GB.

```bash
./parca --debuginfo-upload-max-size=2000000000 # 2GB
```

--------------------------------

### Write Raw Profile Request Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON request body for writing raw pprof-formatted profiles to storage. Includes series, labels, and base64-encoded raw profile data.

```json
{
  "series": [
    {
      "labels": {
        "labels": [
          {"name": "job", "value": "myapp"},
          {"name": "instance", "value": "localhost:6060"}
        ]
      },
      "samples": [
        {
          "raw_profile": "<base64-encoded-pprof-bytes>"
        }
      ],
      "normalized": true
    }
  ]
}
```

--------------------------------

### Basic Scrape Configuration

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/scrape-service.md

Example of a basic scrape configuration in parca.yaml, defining a job named 'myapp' with scrape intervals, timeouts, and specific profiling configurations for CPU and memory.

```yaml
scrape_configs:
  - job_name: "myapp"
    scrape_interval: 10s
    scrape_timeout: 15s
    scheme: http
    static_configs:
      - targets: ["localhost:6060"]
    profiling_config:
      pprof_config:
        cpu:
          enabled: true
          path: /debug/pprof/profile
          delta: true
          seconds: 10
        memory:
          enabled: true
          path: /debug/pprof/allocs

```

--------------------------------

### Set Bearer Token Environment Variable

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Example of setting the PARCA_BEARER_TOKEN environment variable for authentication. This is typically used before starting the Parca binary.

```bash
export PARCA_BEARER_TOKEN=secret-token
./parca

```

--------------------------------

### Startup Error: Port Already in Use

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

This error message indicates that the specified port (e.g., 7070) is already in use by another process, preventing the HTTP server from starting.

```text
Error starting HTTP server: listen tcp :7070: bind: address already in use
```

--------------------------------

### Set up Parca with Tilt for Kubernetes

Source: https://github.com/parca-dev/parca/blob/main/CONTRIBUTING.md

Use Tilt to run the parca-server and parca-ui together for profiling all containers using Kubernetes.

```bash
cd parca

make dev/setup

make dev/up

tilt up
```

--------------------------------

### GET /profiles/types

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Retrieves a list of all available profile types that have been collected by Parca. It can optionally accept start and end timestamps to filter by collection time.

```APIDOC
## GET /profiles/types

### Description
Returns available profile types that have been collected. Optionally accepts `start` and `end` RFC3339 timestamps.

### Method
GET

### Endpoint
/profiles/types

### Parameters
#### Query Parameters
- `start` (string): Optional RFC3339 timestamp.
- `end` (string): Optional RFC3339 timestamp.

### Response
#### Success Response (200)
- `types` (array): An array of profile type objects.
  - `name` (string): The name of the profile type (e.g., "cpu").
  - `sample_type` (string): The unit for samples (e.g., "count").
  - `sample_unit` (string): The unit for samples (e.g., "count").
  - `period_type` (string): The type of period measurement (e.g., "time").
  - `period_unit` (string): The unit for period measurement (e.g., "nanoseconds").
  - `delta` (boolean): Indicates if the type is a delta measurement.

#### Response Example
```json
{
  "types": [
    {
      "name": "cpu",
      "sample_type": "samples",
      "sample_unit": "count",
      "period_type": "time",
      "period_unit": "nanoseconds",
      "delta": false
    }
  ]
}
```
```

--------------------------------

### Query API - Flamegraph Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/query-service.md

Use this snippet to perform a query and retrieve a flamegraph report. Ensure the correct mode and report type are specified.

```bash
curl -X GET "http://localhost:7070/profiles/query?mode=1&single.query=job%3D%22app%22&single.time=2024-01-01T00:30:00Z&report_type=5"
```

--------------------------------

### GET /profiles/labels

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Fetches a list of all available label names that can be used for filtering profiles. The query can be time-bounded using optional start and end RFC3339 timestamps.

```APIDOC
## GET /profiles/labels

### Description
Returns available label names for filtering profiles. Optionally accepts `start` and `end` RFC3339 timestamps.

### Method
GET

### Endpoint
/profiles/labels

### Parameters
#### Query Parameters
- `start` (string): Optional RFC3339 timestamp.
- `end` (string): Optional RFC3339 timestamp.

### Response
#### Success Response (200)
- `label_names` (array): An array of strings, where each string is a label name.

#### Response Example
```json
{
  "label_names": ["job", "instance", "pod", "namespace"]
}
```
```

--------------------------------

### Initialize Profile Store (ColumnStore)

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/server-components.md

Initializes the in-memory columnar storage for profiles using Apache Arrow. Requires logger, registry, and memory allocator.

```go
columnStore, err := profilestore.NewColumnStore(
	logger,
	reg,
	memory.NewGoAllocator(),
	... 
)
```

--------------------------------

### Get Available Profile Types

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Retrieves a list of all profile types that have been collected by Parca. Optional query parameters `start` and `end` can filter by time range.

```json
{
  "types": [
    {
      "name": "cpu",
      "sample_type": "samples",
      "sample_unit": "count",
      "period_type": "time",
      "period_unit": "nanoseconds",
      "delta": false
    }
  ]
}
```

--------------------------------

### Parca Query Language Examples

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/query-service.md

Demonstrates the syntax and usage of the Parca query language for filtering profiles based on labels. Supports exact, not equal, regex match, and regex not match operators.

```plaintext
{label1="value1", label2="value2"}
```

```plaintext
{job="parca"}
```

```plaintext
{job="parca", instance=~"localhost.*"}
```

```plaintext
{job!="test", region="us-east-1"}
```

--------------------------------

### Startup Error: Private Key Mismatch

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

This error message indicates an issue loading the TLS certificate, where the provided private key does not match the public certificate.

```text
Error loading TLS certificate: tls: private key does not match public certificate
```

--------------------------------

### Get Available Label Names

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Fetches a list of all available label names that can be used for filtering profiles. You can optionally specify `start` and `end` query parameters as RFC3339 timestamps.

```json
{
  "label_names": ["job", "instance", "pod", "namespace"]
}
```

--------------------------------

### Get Values for a Specific Label

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Retrieves all unique values associated with a given label name. The `label_name` is a path parameter. Optional `start` and `end` query parameters can filter by time range.

```json
{
  "label_values": ["parca", "prometheus", "grafana"]
}
```

--------------------------------

### Mark Debug Info Upload Finished Request Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

JSON request body to mark a debug info upload as complete, specifying the build ID, upload ID, and type.

```json
{
  "build_id": "abcd1234",
  "upload_id": "session-uuid",
  "type": 0,
  "build_id_type": 1
}
```

--------------------------------

### GET /profiles/labels/{label_name}/values

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Retrieves all unique values for a specified label name. This endpoint requires the `label_name` as a path parameter and can be filtered by time using optional start and end RFC3339 timestamps.

```APIDOC
## GET /profiles/labels/{label_name}/values

### Description
Returns available values for a specific label. Requires `label_name` as a path parameter and optionally accepts `start` and `end` RFC3339 timestamps.

### Method
GET

### Endpoint
/profiles/labels/{label_name}/values

### Parameters
#### Path Parameters
- `label_name` (string): Required - The name of the label to retrieve values for.

#### Query Parameters
- `start` (string): Optional RFC3339 timestamp.
- `end` (string): Optional RFC3339 timestamp.

### Response
#### Success Response (200)
- `label_values` (array): An array of strings, where each string is a value for the specified label.

#### Response Example
```json
{
  "label_values": ["parca", "prometheus", "grafana"]
}
```
```

--------------------------------

### Kubernetes Pod Discovery Configuration

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/scrape-service.md

Example of configuring Kubernetes service discovery to scrape pods in the 'default' namespace. This allows Parca to automatically discover and scrape targets within a Kubernetes cluster.

```yaml
scrape_configs:
  - job_name: "kubernetes"
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names:
            - default

```

--------------------------------

### GET /profiles/query_range

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Queries profiles over a specified time range and aggregates them into time series. It requires a query selector, start and end timestamps, and supports optional step duration, result limits, and summing by labels.

```APIDOC
## GET /profiles/query_range

### Description
Queries profiles over a time range, aggregating into time series. Requires `query`, `start`, and `end` parameters.

### Method
GET

### Endpoint
/profiles/query_range

### Parameters
#### Query Parameters
- `query` (string): Required - Label selector query (e.g., `{job="parca"}`).
- `start` (string): Required - RFC3339 timestamp for the start of the range.
- `end` (string): Required - RFC3339 timestamp for the end of the range.
- `step` (string): Optional - Duration string (e.g., "60s").
- `limit` (integer): Optional - Maximum number of profiles to return.
- `sum_by` (string): Optional, repeatable - Labels to sum by.

### Request Example
```
GET /profiles/query_range?query={job="parca"}&start=2024-01-01T00:00:00Z&end=2024-01-01T01:00:00Z&step=60s&sum_by=job
```

### Response
#### Success Response (200)
- `series` (array): An array of time series data.
  - `labelset` (object): Set of labels associated with the series.
    - `labels` (array): Array of label key-value pairs.
      - `name` (string): Label name.
      - `value` (string): Label value.
  - `samples` (array): Array of data points within the series.
    - `timestamp` (string): RFC3339 timestamp of the sample.
    - `value` (string): The measured value.
    - `value_per_second` (number): The value per second.
    - `duration` (string): The duration of the sample in nanoseconds.
    - `count` (integer): The number of samples.
  - `period_type` (object): Type of period measurement.
    - `type` (string): Type name (e.g., "cpu").
    - `unit` (string): Unit name (e.g., "nanoseconds").
  - `sample_type` (object): Type of sample measurement.
    - `type` (string): Type name (e.g., "samples").
    - `unit` (string): Unit name (e.g., "count").

#### Response Example
```json
{
  "series": [
    {
      "labelset": {
        "labels": [{"name": "job", "value": "parca"}]
      },
      "samples": [
        {
          "timestamp": "2024-01-01T00:00:00Z",
          "value": "1500000",
          "value_per_second": 25.0,
          "duration": "60000000000",
          "count": 10
        }
      ],
      "period_type": {"type": "cpu", "unit": "nanoseconds"},
      "sample_type": {"type": "samples", "unit": "count"}
    }
  ]
}
```
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/parca-dev/parca/blob/main/README.md

Change the current directory to the cloned Parca project directory.

```bash
cd parca
```

--------------------------------

### Get Dropped Targets (HTTP)

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/scrape-service.md

Retrieves scrape targets that have been dropped by appending the 'state=2' query parameter to the HTTP GET request.

```bash
curl -X GET "http://localhost:7070/targets?state=2"
```

--------------------------------

### Query Unimplemented Error Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

An example error response from the Query service indicating that a requested operation, such as the Series endpoint, is not yet implemented.

```json
{
  "code": 12,
  "message": "UNIMPLEMENTED: Series endpoint is not yet implemented",
  "details": []
}
```

--------------------------------

### Parca CLI Help Output

Source: https://github.com/parca-dev/parca/blob/main/README.md

Displays the available command-line flags and their descriptions for configuring Parca. Use these flags to customize its operation.

```txt
Usage: parca [flags]

Flags:
  -h, --help                     Show context-sensitive help.
      --config-path="parca.yaml"
                                 Path to config file.
      --mode="all"               Scraper only runs a scraper that sends to a
                                 remote gRPC endpoint. All runs all components.
      --http-address=":7070"     Address to bind HTTP server to.
      --http-read-timeout=5s     Timeout duration for HTTP server to read
                                 request body.
      --http-write-timeout=1m    Timeout duration for HTTP server to write
                                 response body.
      --port=""                  (DEPRECATED) Use http-address instead.
      --log-level="info"         Log level.
      --log-format="logfmt"      Configure if structured logging as JSON or as
                                 logfmt
      --otlp-address=STRING      The endpoint to send OTLP traces to.
      --otlp-exporter="grpc"     The OTLP exporter to use.
      --otlp-insecure            If true, disables TLS for OTLP exporters (both
                                 gRPC and HTTP).
      --cors-allowed-origins=CORS-ALLOWED-ORIGINS,...
                                 Allowed CORS origins.
      --version                  Show application version.
      --path-prefix=""           Path prefix for the UI
      --mutex-profile-fraction=0
                                 Fraction of mutex profile samples to collect.
      --block-profile-rate=0     Sample rate for block profile.
      --enable-persistence       Turn on persistent storage for the metastore
                                 and profile storage.
      --storage-active-memory=536870912
                                 Amount of memory to use for active storage.
                                 Defaults to 512MB.
      --storage-path="data"      Path to storage directory.
      --storage-enable-wal       Enables write ahead log for profile storage.
      --storage-snapshot-trigger-size=134217728
                                 Number of bytes to trigger a snapshot. Defaults
                                 to 1/4 of active memory. This is only used if
                                 enable-wal is set.
      --storage-row-group-size=8192
                                 Number of rows in each row group during
                                 compaction and persistence. Setting to <= 0
                                 results in a single row group per file.
      --storage-index-on-disk    Whether to store the index on disk instead
                                 of in memory. Useful to reduce the memory
                                 footprint of the store.
      --symbolizer-demangle-mode="simple"
                                 Mode to demangle C++ symbols. Default mode
                                 is simplified: no parameters, no templates, no return type
      --symbolizer-external-addr-2-line-path=""
                                 Path to addr2line utility, to be used for
                                 symbolization instead of native implementation
      --symbolizer-number-of-tries=3
                                 Number of tries to attempt to symbolize an
                                 unsybolized location
      --debuginfo-cache-dir="/tmp"
                                 Path to directory where debuginfo is cached.
      --debuginfo-upload-max-size=1000000000
                                 Maximum size of debuginfo upload in bytes.
      --debuginfo-upload-max-duration=15m
                                 Maximum duration of debuginfo upload.
      --debuginfo-uploads-signed-url
                                 Whether to use signed URLs for debuginfo
                                 uploads.
      --debuginfod-upstream-servers=debuginfod.elfutils.org,...
                                 Upstream debuginfod servers. Defaults to
                                 debuginfod.elfutils.org. It is an ordered
                                 list of servers to try. Learn more at
                                 https://sourceware.org/elfutils/Debuginfod.html
      --debuginfod-http-request-timeout=5m
                                 Timeout duration for HTTP request to upstream
                                 debuginfod server. Defaults to 5m
      --profile-share-server="api.pprof.me:443"
                                 gRPC address to send share profile requests to.
      --store-address=STRING     gRPC address to send profiles and symbols to.
      --bearer-token=STRING      Bearer token to authenticate with store
                                 ($PARCA_BEARER_TOKEN).
      --bearer-token-file=STRING
                                 File to read bearer token from to authenticate
                                 with store.

```

--------------------------------

### Get Active Targets Only (HTTP)

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/scrape-service.md

Retrieves only the currently active scrape targets by appending the 'state=1' query parameter to the HTTP GET request.

```bash
curl -X GET "http://localhost:7070/targets?state=1"
```

--------------------------------

### Configure Metadata Store (Badger Options)

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/server-components.md

Defines options for the Badger key-value store used for profile metadata. Can be configured for in-memory or persistent storage.

```go
badger.Options{
	InMemory: !flags.EnablePersistence,
	Dir:      filepath.Join(flags.Storage.Path, "metastore"),
	// ...
}
```

--------------------------------

### WriteRaw Resource Exhausted Error Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

An example of a RESOURCE_EXHAUSTED error from the WriteRaw profile store, indicating that a resource limit, such as active storage memory, has been exceeded.

```json
{
  "code": 8,
  "message": "RESOURCE_EXHAUSTED: active storage memory limit exceeded",
  "details": []
}
```

--------------------------------

### Enable Persistent Storage

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/configuration.md

Enable persistent storage for profiles and configure the directory. Requires `--storage-path`.

```bash
./parca --enable-persistence --storage-path=/data/parca
```

--------------------------------

### QueryRange Invalid Argument Error Example

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

An example of an error response when invalid arguments are provided to the QueryRange service, such as incorrect query syntax or malformed timestamps.

```json
{
  "code": 3,
  "message": "INVALID_ARGUMENT: invalid query syntax: unexpected end of input",
  "details": []
}
```

--------------------------------

### Startup Error: Invalid Storage Path

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

This error message indicates a failure to initialize storage due to insufficient permissions for creating directories at the specified storage path.

```text
Error initializing storage: mkdir: permission denied for /data/parca
```

--------------------------------

### Example: Timeout Error

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

An example of a 'DEADLINE_EXCEEDED' error, occurring when a query takes too long or a scrape exceeds the configured timeout. Try reducing the time range, applying filters, or increasing the timeout settings.

```text
GET /profiles/query_range?...  (no response for 5 minutes)
error: DEADLINE_EXCEEDED: query execution timeout
```

--------------------------------

### Get Agents

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/README.md

Fetches a list of active Parca agents.

```bash
curl http://localhost:7070/agents
```

--------------------------------

### Startup Error: Config File Not Found

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

This error message indicates that the Parca configuration file ('parca.yaml') could not be found during server initialization.

```text
Error reading config: open parca.yaml: no such file or directory
```

--------------------------------

### Build and Run Parca Locally

Source: https://github.com/parca-dev/parca/blob/main/CONTRIBUTING.md

Compile the Parca binary and run it locally to test changes. The UI will be available at http://localhost:7070.

```bash
cd parca

make build
./bin/parca
```

--------------------------------

### GET /targets

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Returns configured scrape targets and their status. Can be filtered by state.

```APIDOC
## GET /targets

### Description
Returns configured scrape targets and their status.

### Method
GET

### Endpoint
/targets

### Parameters
#### Query Parameters
- `state` (integer) - Optional - Filter by state (0=any, 1=active, 2=dropped)

### Response
#### Success Response (200 OK)
- `targets` (object) - An object containing scrape target information.
  - `parca` (object) - Target information for Parca.
    - `targets` (array) - Array of discovered targets.
      - `discovered_labels` (object) - Labels discovered by the target.
        - `labels` (array) - Array of label key-value pairs.
          - `name` (string) - Label name.
          - `value` (string) - Label value.
      - `labels` (object) - Labels associated with the target.
        - `labels` (array) - Array of label key-value pairs.
          - `name` (string) - Label name.
          - `value` (string) - Label value.
      - `last_error` (string) - The last error encountered during scraping.
      - `last_scrape` (string) - Timestamp of the last successful scrape.
      - `last_scrape_duration` (string) - Duration of the last scrape.
      - `url` (string) - The URL of the scrape target.
      - `health` (integer) - Health status of the target (e.g., 1 for healthy).

### Response Example
```json
{
  "targets": {
    "parca": {
      "targets": [
        {
          "discovered_labels": {
            "labels": [
              {"name": "__scheme__", "value": "http"},
              {"name": "__address__", "value": "localhost:7070"}
            ]
          },
          "labels": {
            "labels": [
              {"name": "job", "value": "parca"},
              {"name": "instance", "value": "localhost:7070"}
            ]
          },
          "last_error": "",
          "last_scrape": "2024-01-01T12:30:45Z",
          "last_scrape_duration": "250ms",
          "url": "http://localhost:7070/debug/pprof/profile",
          "health": 1
        }
      ]
    }
  }
}
```

### Status Codes
- `200 OK`: Targets returned
- `400 Bad Request`: Invalid state parameter
```

--------------------------------

### Startup Error: Invalid Certificate

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/errors.md

This error message indicates a problem loading the TLS certificate, specifically that the certificate data could not be found in the provided input.

```text
Error loading TLS certificate: tls: failed to find certificate PEM data in certificate input
```

--------------------------------

### GET /agents

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Returns metadata about agents that have sent profiles. No query parameters are required.

```APIDOC
## GET /agents

### Description
Returns metadata about agents that have sent profiles.

### Method
GET

### Endpoint
/agents

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200 OK)
- `agents` (array) - An array of agent metadata objects.
  - `id` (string) - The agent's unique identifier.
  - `labels` (object) - Labels associated with the agent.
    - `labels` (array) - Array of label key-value pairs.
      - `name` (string) - Label name.
      - `value` (string) - Label value.
  - `last_profile_received` (string) - Timestamp of the last received profile.

### Response Example
```json
{
  "agents": [
    {
      "id": "parca-agent-0",
      "labels": {
        "labels": [
          {"name": "instance", "value": "localhost:7071"}
        ]
      },
      "last_profile_received": "2024-01-01T12:30:45Z"
    }
  ]
}
```

### Status Codes
- `200 OK`: Agents returned
- `500 Internal Server Error`: Error retrieving agents
```

--------------------------------

### POST /initiateupload

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Initiates a debug info upload and returns a signed URL and upload instructions.

```APIDOC
## POST /initiateupload

### Description
Initiates debug info upload and returns strategy.

### Method
POST

### Endpoint
/initiateupload

### Parameters
#### Request Body
- `build_id` (string) - Required - The build ID.
- `hash` (string) - Required - The hash of the debug info.
- `type` (integer) - Optional - Type of debug info.
- `build_id_type` (integer) - Optional - Type of build ID.

### Request Example
```json
{
  "build_id": "abcd1234",
  "hash": "sha256:abc123...",
  "type": 0,
  "build_id_type": 1
}
```

### Response
#### Success Response (200 OK)
- `upload_id` (string) - The unique identifier for the upload session.
- `signed_url` (string) - The signed URL for uploading the debug info.
- `upload_instructions` (string) - Instructions for uploading.

### Response Example
```json
{
  "upload_id": "session-uuid",
  "signed_url": "https://storage.example.com/...",
  "upload_instructions": "POST to signed URL"
}
```

### Status Codes
- `200 OK`: Upload initiated
- `400 Bad Request`: Invalid parameters
- `409 Conflict`: Upload already in progress
```

--------------------------------

### InitiateUpload

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/debuginfo-service.md

Initiates a debug info upload session by returning an upload strategy and relevant information for a given build ID.

```APIDOC
## POST /initiateupload

### Description
Returns upload strategy and information for a given build ID.

### Method
POST

### Endpoint
/initiateupload

### Parameters
#### Request Body
- **build_id** (string) - Yes - Build ID to initiate upload for
- **hash** (string) - Yes - Hash of the debug info
- **type** (DebuginfoType) - Yes - Type of debug info
- **build_id_type** (BuildIDType) - Yes - Format of build ID

### Request Example
{
  "build_id": "abcd1234",
  "hash": "sha256:abc123...",
  "type": 1,
  "build_id_type": 1
}

### Response
#### Success Response (200)
- **upload_id** (string) - Unique identifier for this upload session
- **signed_url** (string) - Signed URL for direct upload (if using object storage)
- **upload_instructions** (string) - Instructions for the upload process

#### Response Example
{
  "upload_id": "upload-session-uuid",
  "signed_url": "https://storage.example.com/upload?token=xyz...",
  "upload_instructions": "POST debug info to signed URL"
}
```

--------------------------------

### Get Available Profile Types

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/README.md

Retrieves a list of all available profile types supported by Parca.

```bash
curl http://localhost:7070/profiles/types
```

--------------------------------

### GET /profiles/series

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

This endpoint is intended to return label value series matching a selector but is currently unimplemented.

```APIDOC
## GET /profiles/series

### Description
Returns label value series matching a selector. This endpoint is currently unimplemented.

### Method
GET

### Endpoint
/profiles/series

### Parameters
#### Query Parameters
- `query` (string): Optional - Label selector.
- `start` (string): Optional RFC3339 timestamp.
- `end` (string): Optional RFC3339 timestamp.

### Response
#### Error Response (501)
- `501 Not Implemented`: Indicates that the endpoint is not yet implemented.
```

--------------------------------

### Run Go Tests

Source: https://github.com/parca-dev/parca/blob/main/CONTRIBUTING.md

Execute Go tests to verify your changes in the Parca project.

```bash
cd parca && make go/test
```

--------------------------------

### Check if Debug Info Upload Should Initiate (Bash)

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/debuginfo-service.md

Sends a POST request to the /shouldinitiateupload endpoint to determine if an upload for a given build ID and hash should proceed. Requires Content-Type header and a JSON payload.

```bash
curl -X POST http://localhost:7070/shouldinitiateupload \
  -H "Content-Type: application/json" \
  -d '{
    "build_id": "abcd1234",
    "hash": "sha256:abc123...",
    "type": 1
  }'
```

--------------------------------

### Build Parca Binary with Embedded Assets

Source: https://github.com/parca-dev/parca/blob/main/ui/README.md

Build the main 'parca' binary, embedding the production build artifacts and static assets. Refer to pkg.go.dev/embed for details.

```shell
make build
```

--------------------------------

### GET /metrics

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/endpoints.md

Prometheus metrics endpoint. This endpoint exposes system metrics in Prometheus text format, if configured.

```APIDOC
## GET /metrics

### Description
Prometheus metrics endpoint (if exposed).

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
Prometheus text format metrics

#### Status Codes
- 200 OK: Metrics returned
- 404 Not Found: Metrics not exposed
```

--------------------------------

### Get Label Values

Source: https://github.com/parca-dev/parca/blob/main/_autodocs/api-reference/query-service.md

Retrieves the set of values for a given label name within a specified time range.

```APIDOC
## GET /profiles/labels/{label_name}/values

### Description
Returns the set of values for a given label name within a time range.

### Method
GET

### Endpoint
/profiles/labels/{label_name}/values

### Parameters
#### Path Parameters
- **label_name** (string) - Required - Label name to get values for

#### Query Parameters
- **start** (Timestamp) - Optional - Start of query time window
- **end** (Timestamp) - Optional - End of query time window
- **match** (repeated string) - Optional - Label matchers to filter by

### Response
#### Success Response (200)
- **label_values** (repeated string) - Values for the requested label

### Response Example
```json
{
  "label_values": ["parca", "prometheus", "grafana", "alertmanager"]
}
```
```

--------------------------------

### Tagging a New Release via CLI

Source: https://github.com/parca-dev/parca/blob/main/RELEASE.md

Use this command to tag a new release locally and push it to the origin. Ensure you replace 'v2.1.3' with your actual version number. A signed tag is preferred; use '-a' instead of '-s' if GPG signing is not possible.

```bash
git tag -s "v2.1.3" -m "v2.1.3"
git push origin "v2.1.3"
```