### Install StatsHouse API/UI component

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/admin/install.md

Example command to start the API/UI component with required configuration parameters.

```bash
statshouse-api --clickhouse-v2-addrs=XXX.X.X.X:XXXX \
--listen-addr=:YYYYY --disk-cache=/var/lib/statshouse/cache/api/mapping_cache.sqlite3 \
--static-dir=/usr/lib/statshouse-api/statshouse-ui/
```

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

### Metadata Service Installation Script Example

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/admin/install.md

Example command to install and run the StatsHouse metadata service, specifying database and binlog paths.

```shell
statshouse-metadata --db-path=/var/lib/statshouse/metadata/db --binlog-prefix=/var/lib/statshouse/metadata/binlog/bl
```

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

### Run StatsHouse Example Application

Source: https://github.com/vkcom/statshouse/blob/master/docs/quickstart.md

Start a simple instrumented web server to send metrics to the running StatsHouse instance. This requires the StatsHouse instance to be already launched.

```go
go run ./cmd/statshouse-example/statshouse-example.go
```

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

### Local Development Setup

Source: https://context7.com/vkcom/statshouse/llms.txt

Commands to clone, start, and test the StatsHouse stack locally.

```bash
# Clone the repository
git clone https://github.com/VKCOM/statshouse
cd statshouse

# Start local StatsHouse instance (requires Docker)
./localrun.sh

# The UI will be available at http://localhost:10888

# Run the example instrumented web server
go run ./cmd/statshouse-example/statshouse-example.go

# Access the example server at http://localhost:3333
# View metrics at http://localhost:10888/view?live=1&f=-300&t=0
```

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

### Install Dependencies

Source: https://github.com/vkcom/statshouse/blob/master/grafana-plugin-ui/README.md

Run this command to install the necessary project dependencies.

```bash
yarn install
```

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

### Install Dependencies and Start Dev Mode

Source: https://github.com/vkcom/statshouse/blob/master/statshouse-ui/README.md

Install project dependencies and start the development server for the StatsHouse UI. Requires Node 20+.

```shell
npm install
npm run start
```

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

### Example env.conf for Host Metric Tags

Source: https://context7.com/vkcom/statshouse/llms.txt

Example configuration file for setting environment and datacenter tags for host metrics.

```properties
# env=production
# datacenter=us-east-1
# service=web
```

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

### Start Local Development Server

Source: https://github.com/vkcom/statshouse/blob/master/website/README.md

Starts a local development server. Changes are reflected live without restarting.

```bash
$ yarn start
```

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

### Start API Service with UI

Source: https://context7.com/vkcom/statshouse/llms.txt

Start the StatsHouse API service, configuring ClickHouse addresses, listen address, disk cache, and static UI directory.

```bash
statshouse-api \
  --clickhouse-v2-addrs=clickhouse1:9000,clickhouse2:9000,clickhouse3:9000 \
  --listen-addr=:10888 \
  --disk-cache=/var/lib/statshouse/cache/api/mapping_cache.sqlite3 \
  --static-dir=/usr/lib/statshouse-api/statshouse-ui/
```

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

### ClickHouse Storage Configuration Example

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/admin/install.md

Example configuration for ClickHouse storage policies, defining disk paths and a policy to use SSDs first, then HDDs.

```xml
<storage_configuration>
<disks>
  <clickhouse_fast>
    <path>/var/lib/clickhouse-fast/</path>
  </clickhouse_fast>
</disks>
<policies>
  <ssd_then_hdd>
    <volumes>
      <ssd>
        <disk>clickhouse_fast</disk>
      </ssd>
      <hdd>
        <disk>default</disk>
      </hdd>
    </volumes>
  </ssd_then_hdd>
</policies>
</storage_configuration>
```

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

### Local Development Setup

Source: https://context7.com/vkcom/statshouse/llms.txt

Instructions for setting up a complete StatsHouse stack locally using Docker.

```APIDOC
## Local Development Setup

### Description
Run a complete StatsHouse stack locally using Docker for development and testing.

### Steps
```bash
# Clone the repository
git clone https://github.com/VKCOM/statshouse
cd statshouse

# Start local StatsHouse instance (requires Docker)
./localrun.sh

# The UI will be available at http://localhost:10888

# Run the example instrumented web server
go run ./cmd/statshouse-example/statshouse-example.go

# Access the example server at http://localhost:3333
# View metrics at http://localhost:10888/view?live=1&f=-300&t=0
```
```

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

### Start Metadata Service

Source: https://context7.com/vkcom/statshouse/llms.txt

Start the StatsHouse metadata service, specifying the database path and binlog prefix.

```bash
statshouse-metadata \
  --db-path=/var/lib/statshouse/metadata/db \
  --binlog-prefix=/var/lib/statshouse/metadata/binlog/bl
```

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

### Start Agent with Environment Configuration

Source: https://context7.com/vkcom/statshouse/llms.txt

Configure the agent to use environment-specific settings from a file for host metrics.

```bash
statshouse agent \
  --agg-addr=aggregator1:13336 \
  --aes-pwd-file=/etc/engine/pass \
  --cache-dir=/var/lib/statshouse/ \
  --env-file-path=/etc/statshouse/env.conf
```

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

### Run ingress proxies

Source: https://github.com/vkcom/statshouse/blob/master/localdebug/README.md

Commands to start ingress proxies using specific key directories.

```bash
./run-ingress.sh
./run-ingress2.sh
```

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

### Start Agent with Aggregator Addresses

Source: https://context7.com/vkcom/statshouse/llms.txt

Start the StatsHouse agent, specifying aggregator addresses, password file, and cache directory.

```bash
statshouse agent \
  --agg-addr=10.0.0.1:13336,10.0.0.2:13336,10.0.0.3:13336 \
  --aes-pwd-file=/etc/engine/pass \
  --cache-dir=/var/lib/statshouse/
```

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

### Run agents with ingress keys

Source: https://github.com/vkcom/statshouse/blob/master/localdebug/README.md

Commands to start agents connected through specific ingress proxies.

```bash
./run-agent-ingress-key1.sh
./run-agent-ingress-key2.sh
./run-agent-ingress2-key3.sh
```

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

### PromQL Query Examples

Source: https://context7.com/vkcom/statshouse/llms.txt

Common PromQL patterns for querying, aggregating, and performing math on metrics.

```promql
# Basic metric query
my_metric

# Filter by tag values
api_requests{method="GET", status="200"}

# Aggregate by tag
sum by (status) (api_requests)

# Rate calculation (requests per second)
rate(api_requests[5m])

# Average response time with grouping
avg by (handler) (response_time)

# Percentile queries
histogram_quantile(0.95, response_time)

# Mathematical operations
sum(api_requests{status=~"5.."}) / sum(api_requests) * 100

# Compare with time offset (vs yesterday)
api_requests - api_requests offset 1d

# Complex aggregation
topk(10, sum by (endpoint) (rate(api_requests[5m])))

# Multiple metrics in expression
sum(response_time) / sum(api_requests)
```

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

### Install Agent (Debian/Ubuntu)

Source: https://context7.com/vkcom/statshouse/llms.txt

Install the StatsHouse agent package on Debian or Ubuntu systems.

```bash
dpkg -i statshouse_2024.05.1-focal_amd64.deb
```

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

### Advanced Migration Test Scenarios

Source: https://github.com/vkcom/statshouse/blob/master/cmd/test-migration/README.md

Examples demonstrating specific migration configurations including time windows and custom shard counts.

```bash
# Migrate current hour for shard 1 (V2)
./test-migration -source v2 -shard-key 1

# Migrate with second-level precision for a 5-minute window
./test-migration -source v2 -time 1672531200-1672531500 -step 1s -shard-key 1

# Migrate with custom shard configuration (8 shards instead of 16)
./test-migration -source v2 -time 1672531200 -total-shards 8 -shard-key 1
```

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

### Install StatsHouse Aggregator

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/admin/install.md

Use this command to install the StatsHouse aggregator on each ClickHouse replica. Ensure all required parameters such as cluster name, database address, and encryption key path are provided.

```bash
statshouse aggregator --cluster=test_shard_localhost --agg-addr=':13336' --aes-pwd-file=/etc/engine/pass \
--kh=XXX.X.X.X:XXXX --cache-dir=/var/lib/statshouse/cache/aggregator -u=root -g=root
```

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

### Install Agent (RHEL/CentOS)

Source: https://context7.com/vkcom/statshouse/llms.txt

Install the StatsHouse agent package on RHEL or CentOS systems.

```bash
rpm -i statshouse-2024.05.1-1.almalinux9.x86_64.rpm
```

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

### Start Aggregator

Source: https://context7.com/vkcom/statshouse/llms.txt

Start the StatsHouse aggregator on each ClickHouse replica, specifying cluster, address, password file, ClickHouse host, and cache directory.

```bash
statshouse aggregator \
  --cluster=production_cluster \
  --agg-addr=':13336' \
  --aes-pwd-file=/etc/engine/pass \
  --kh=localhost:9000 \
  --cache-dir=/var/lib/statshouse/cache/aggregator \
  -u=statshouse -g=statshouse
```

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

### Query metric counter with __what__

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/guides/query-wth-promql.md

Example of selecting the count aggregate for a specific metric.

```text
api_requests{__what__="count"}
```

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

### Start Agent with Custom UDP Listen Address

Source: https://context7.com/vkcom/statshouse/llms.txt

Configure the agent to listen on a custom UDP address and port for metrics.

```bash
statshouse agent \
  --agg-addr=aggregator1:13336,aggregator2:13336 \
  --aes-pwd-file=/etc/engine/pass \
  --cache-dir=/var/lib/statshouse/ \
  --addr=0.0.0.0:13337
```

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

### User-Guided Sampling Example

Source: https://context7.com/vkcom/statshouse/llms.txt

JSON format for explicit counter with sampled values, indicating total events and the sampled values.

```json
{"metrics":[{
  "name": "sampled_latency",
  "tags": {},
  "counter": 6,
  "value": [1, 2, 3]
}]}
```

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

### Install StatsHouse Agent

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/admin/install.md

Install the StatsHouse agent on machines sending metrics. This command configures the agent to connect to aggregators, specifying aggregator addresses, encryption key path, and cache directory.

```bash
statshouse agent --agg-addr=XX.XXX.XXX.XXX:XXXX,YY.YYY.YYY.YYY:YYYY,ZZ.ZZZ.ZZZ.ZZZ:ZZZZ \
--aes-pwd-file=/etc/engine/pass --cache-dir=/var/lib/statshouse/
```

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

### GET /api/metrics-list

Source: https://context7.com/vkcom/statshouse/llms.txt

Lists all available metrics in the system.

```APIDOC
## GET /api/metrics-list

### Description
Retrieves a list of all metrics currently registered in the system.

### Method
GET

### Endpoint
/api/metrics-list

### Parameters
#### Query Parameters
- **full** (integer) - Optional - If set to 1, returns full details including disabled metrics

### Response
#### Success Response (200)
- **data** (object) - Contains a list of metrics
```

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

### Run StatsHouse with Tmux

Source: https://github.com/vkcom/statshouse/blob/master/docs/quickstart.md

Execute this script to start a local StatsHouse instance and open the UI. Ensure you are in the 'localdebug' directory.

```shell
cd localdebug
./run-in-tmux.sh
```

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

### Tag Index Usage Example

Source: https://context7.com/vkcom/statshouse/llms.txt

JSON format demonstrating the use of tag indices instead of names for metrics.

```json
{"metrics":[{
  "name": "my_metric",
  "tags": {"0": "production", "1": "web-server-01"},
  "counter": 1
}]}
```

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

### Manage tmux sessions

Source: https://github.com/vkcom/statshouse/blob/master/localdebug/README.md

Commands to start or gracefully stop the StatsHouse tmux environment.

```bash
./run-in-tmux.sh
```

```bash
./stop-tmux.sh
```

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

### Counter Metric Example

Source: https://context7.com/vkcom/statshouse/llms.txt

JSON format for sending a counter metric, including name, tags, and count.

```json
{"metrics":[{
  "name": "http_requests",
  "tags": {"method": "GET", "status": "200"},
  "counter": 1
}]}
```

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

### Example Host Metric Tag Configuration

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/admin/host-metrics.md

Define standard host metric tags within a YAML file. Ensure consistent naming conventions across your organization for tag values.

```yaml
hostname: myhost
env: production
group: group_name
dc: data_center_name
region: spb
owner: example_team
```

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

### Send tagged metrics in Python

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/guides/design-metric.md

Examples of sending metrics with tags using the Python client library to enable filtering and grouping.

```Python
statshouse.value("error_rate", {"platform": "web"}, 42.5)
                   ↑                 ↑         ↑      ↑          
                metric name          ↑         ↑   measurement      
                                 tag name      ↑       
                                             tag value 
```

```Python
statshouse.value("request_rate", {"env": "production", "region": "moscow"}, 42.5)
                   ↑                 ↑         ↑           ↑        ↑         ↑
                metric name          ↑         ↑           ↑        ↑      measurement
                                 tag name      ↑       tag name     ↑
                                             tag value            tag value   
```

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

### Value Metric Example

Source: https://context7.com/vkcom/statshouse/llms.txt

JSON format for sending a value metric, including name, tags, and an array of values for statistical aggregation.

```json
{"metrics":[{
  "name": "response_time_seconds",
  "tags": {"handler": "/api/users"},
  "value": [0.125, 0.089, 0.203, 0.156]
}]}
```

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

### Run StatsHouse locally

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/quick-start.md

Clones the repository and executes the local run script. Requires Docker to be installed on the host system.

```shell
git clone https://github.com/VKCOM/statshouse
cd statshouse
./localrun.sh
```

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

### Unique Counter Metric Example

Source: https://context7.com/vkcom/statshouse/llms.txt

JSON format for sending a unique counter metric (HyperLogLog) for cardinality estimation, including name, tags, and an array of values.

```json
{"metrics":[{
  "name": "unique_visitors",
  "tags": {"page": "homepage"},
  "unique": [12345, 67890, 11111, 22222]
}]}
```

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

### Start API Service in Insecure Mode

Source: https://context7.com/vkcom/statshouse/llms.txt

Start the StatsHouse API service in insecure mode for development, disabling authentication.

```bash
statshouse-api \
  --clickhouse-v2-addrs=localhost:9000 \
  --listen-addr=:10888 \
  --disk-cache=/var/lib/statshouse/cache/api/mapping_cache.sqlite3 \
  --static-dir=/usr/lib/statshouse-api/statshouse-ui/ \
  --insecure-mode
```

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

### Build and Run Basic Migration Tests

Source: https://github.com/vkcom/statshouse/blob/master/cmd/test-migration/README.md

Commands to compile the migration tool and execute basic migration tasks from V2 source tables.

```bash
# Build the test tool
go build -o test-migration ./cmd/test-migration/

# Migrate from V2 (default)
./test-migration -source v2 -time 1672531200 -shard-key 1

# Migrate a range of timestamps with second-level precision
./test-migration -source v2 -time 1672531200-1672531260 -step 1s -shard-key 1
```

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

### Run UI build and linting

Source: https://github.com/vkcom/statshouse/blob/master/localdebug/README.md

Commands to compile and lint the UI code.

```bash
statshouse-ui$> npm run tsc
statshouse-ui$> npm run lint
```

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

### Build Plugin in Production Mode

Source: https://github.com/vkcom/statshouse/blob/master/grafana-plugin-ui/README.md

Execute this command to create an optimized build of the plugin for production deployment.

```bash
yarn build
```

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

### GET /api/metric

Source: https://context7.com/vkcom/statshouse/llms.txt

Retrieves metadata and configuration for a specific metric.

```APIDOC
## GET /api/metric

### Description
Fetches the configuration, description, and tag definitions for a specific metric.

### Method
GET

### Endpoint
/api/metric

### Parameters
#### Query Parameters
- **s** (string) - Required - Metric name

### Response
#### Success Response (200)
- **data** (object) - Contains metric configuration details
```

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

### Build and run daemons

Source: https://github.com/vkcom/statshouse/blob/master/localdebug/README.md

Commands to build the project and launch individual daemons in separate terminal tabs.

```bash
./build.sh
```

```bash
./run-metadata.sh
```

```bash
./run-aggregator.sh
```

```bash
./run-api.sh
```

```bash
./run-agent.sh
```

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

### Build Plugin in Development Mode

Source: https://github.com/vkcom/statshouse/blob/master/grafana-plugin-ui/README.md

Use this command to build the plugin for development, which often includes watch mode for continuous rebuilding.

```bash
yarn dev
```

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

### Build Static Website

Source: https://github.com/vkcom/statshouse/blob/master/website/README.md

Generates static content for hosting. The output is placed in the 'build' directory.

```bash
$ yarn build
```

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

### GET /api/query

Source: https://context7.com/vkcom/statshouse/llms.txt

Queries metric data with support for time ranges, aggregation, and tag filtering.

```APIDOC
## GET /api/query

### Description
Retrieves metric data based on specified time ranges, aggregation functions, and optional tag filters.

### Method
GET

### Endpoint
/api/query

### Parameters
#### Query Parameters
- **s** (string) - Required - Metric name
- **f** (integer) - Required - Start time (timestamp or relative)
- **t** (integer) - Required - End time (timestamp or relative)
- **w** (integer) - Required - Window size
- **qw** (string) - Required - Aggregation function (e.g., count_norm, avg, p95)
- **v** (integer) - Required - API version
- **n** (integer) - Required - Number of series
- **qf** (string) - Optional - Tag filter (e.g., key-value)
- **qb** (string) - Optional - Tag breakdown
- **df** (string) - Optional - Data format (e.g., csv)

### Response
#### Success Response (200)
- **series** (object) - Contains time arrays, metadata, and data points
- **sampling_factor_src** (float) - Source sampling factor
- **sampling_factor_agg** (float) - Aggregation sampling factor
```

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

### Collect Metrics with C++ Client

Source: https://context7.com/vkcom/statshouse/llms.txt

Initialize a registry and record value, counter, and unique metrics using the header-only C++ interface.

```cpp
#include "statshouse.hpp"
#include <cstdio>

using namespace statshouse;

// Initialize registry with optional debug logging
Registry r{{
    logger: puts
}};

int main() {
    // Create a metric reference for efficient repeated use
    auto latency = r.metric("request_latency")
        .tag("service", "api")
        .tag("method", "GET")
        .event_metric_ref();

    // Record value metrics
    latency.write_value(42.5);  // latency in milliseconds

    // Record counter metrics
    auto requests = r.metric("http_requests")
        .tag("status", "200")
        .event_metric_ref();
    requests.write_count(1);

    // Record unique values
    auto users = r.metric("unique_users")
        .tag("platform", "ios")
        .event_metric_ref();
    users.write_unique(12345);  // user ID

    // Multiple values in single write
    std::vector<double> values = {1.5, 2.3, 0.8, 3.1};
    latency.write_values(values.data(), values.size());

    return 0;
}
```

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

### Record Metrics with Go Client

Source: https://context7.com/vkcom/statshouse/llms.txt

Use the Go client library to record values, counters, and unique metrics with automatic buffering.

```go
package main

import (
    "time"
    "github.com/VKCOM/statshouse-go"
)

func main() {
    // Record a value metric with named tags
    statshouse.NamedValue("response_time",
        statshouse.NamedTags{
            {"handler", "/api/users"},
            {"status", "ok"},
        }, 0.125) // response time in seconds

    // Record a counter metric
    statshouse.NamedCount("api_requests",
        statshouse.NamedTags{
            {"method", "GET"},
            {"endpoint", "/users"},
        }, 1)

    // Record unique values (e.g., unique user IDs)
    statshouse.NamedUnique("unique_visitors",
        statshouse.NamedTags{
            {"page", "homepage"},
        }, 12345) // user ID

    // Use metric references for high-frequency recording
    responseMetric := statshouse.GetMetricRef("http_response_time")
    for i := 0; i < 1000; i++ {
        start := time.Now()
        // ... do work ...
        responseMetric.Value(time.Since(start).Seconds())
    }

    // Start regular measurement for runtime metrics
    id := statshouse.StartRegularMeasurement(func(client *statshouse.Client) {
        m := client.MetricNamedRef("memory_usage",
            statshouse.NamedTags{{"type", "heap"}})
        m.Value(float64(getHeapSize()))
    })
    defer statshouse.StopRegularMeasurement(id)
}
```

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

### Query histogram percentiles

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/guides/query-wth-promql.md

Example of retrieving the 99th percentile for a metric using the __what__ selector.

```text
api_requests{__what__="p99"}
```

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

### Initialize Swagger UI for StatsHouse

Source: https://github.com/vkcom/statshouse/blob/master/statshouse-ui/public/openapi/index.html

Configures and mounts the Swagger UI instance using the local openapi.json file.

```javascript
window.onload = () => { window.ui = SwaggerUIBundle({ url: './openapi.json', dom_id: '#swagger-ui', }); };
```

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

### Perform User-Guided Sampling

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/overview/concepts.md

Specify a counter for a metric to control memory footprint by simulating multiple events for a given set of values.

```bash
`{"metrics":[{"name":"my_metric","tags":{},"counter":6, "value":[1, 2, 3]}]}`
```

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

### Deploy Website (No SSH)

Source: https://github.com/vkcom/statshouse/blob/master/website/README.md

Deploys the website without using SSH. Replace '<Your GitHub username>' with your actual username.

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

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

### Run Plugin in Watch Mode

Source: https://github.com/vkcom/statshouse/blob/master/grafana-plugin-ui/README.md

This command builds the plugin and automatically recompiles it when source files change.

```bash
yarn watch
```

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

### Define a JSON packet metric event

Source: https://github.com/vkcom/statshouse/blob/master/website/docs/overview/concepts.md

Example of sending a packet count event with JSON format and ok status to the StatsHouse agent.

```json
    {"metrics":[ {"name": "toy_packets_count",
     "tags":{"format": "JSON", "status": "ok"},
     "counter": 1}] }
```

```json
    {"metrics":[ {"name": "toy_packets_count",
     "tags":{"format": "TL", "status": "error_too_short"},
     "counter": 1} ]}
```

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

### Deploy Website (SSH)

Source: https://github.com/vkcom/statshouse/blob/master/website/README.md

Deploys the website using SSH. This command builds the site and pushes to the 'gh-pages' branch.

```bash
$ USE_SSH=true yarn deploy
```