### Startup Example with Error Handling

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

Demonstrates a typical way to start the ClickHouse Exporter in a Go application, including basic error handling for the startup process.

```go
func main() {
	// ... CLI flag parsing ...

	exporter, err := NewExporter(ExporterConfig{
		ClickHouseHost: *clickhouseHost,
		ClickHousePort: *clickhousePort,
		ScrapeInterval: *scrapeInterval,
	})
	if err != nil {
		log.Fatal().Err(err).Msg("Failed to create exporter")
	}

	prometheus.MustRegister(exporter)

	// ... HTTP server setup ...
}
```

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

### Quick Reference Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

A concise example provided for quick reference, likely showing a common or essential way to run the exporter.

```bash
# Quick reference: Run exporter with default settings
./clickhouse_exporter
```

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

### Start Exporter with Default Configuration

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

Starts the exporter on the default port, connecting to a local ClickHouse instance. No additional setup is required.

```bash
./clickhouse_exporter
```

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

### Run ClickHouse Exporter with Scrape URI

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

Example of running the ClickHouse exporter, specifying the scrape URI for ClickHouse. This is a standard way to start the exporter.

```bash
# Valid
./clickhouse_exporter -scrape_uri=http://localhost:8123/
```

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

### Scenario Solution Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

This example illustrates a solution for a specific scenario, likely demonstrating how to configure or use the exporter to achieve a particular outcome. The exact scenario is not detailed here.

```bash
# Example scenario solution
./clickhouse_exporter --clickhouse.host=db.example.com --clickhouse.user=readonly --clickhouse.password=secret --web.listen-address=:9200
```

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

### HTTP Request Examples

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

Examples demonstrating how to interact with the ClickHouse Exporter's HTTP endpoints, including fetching metrics and configuring Prometheus.

```bash
# Fetch metrics from the exporter's default endpoint
curl http://localhost:9100/metrics

# Fetch metrics from a custom endpoint
curl http://localhost:9100/metrics?target=my_clickhouse_instance

# Example Prometheus configuration snippet
- job_name: 'clickhouse_exporter'
  static_configs:
    - targets: ['localhost:9100']

# Example Prometheus configuration snippet with custom scrape interval
- job_name: 'clickhouse_exporter_custom_interval'
  scrape_interval: 15s
  static_configs:
    - targets: ['localhost:9100']

# Example Prometheus configuration snippet with TLS enabled
- job_name: 'clickhouse_exporter_tls'
  scheme: https
  tls_config:
    insecure_skip_verify: true
  static_configs:
    - targets: ['localhost:9100']

# Example Prometheus configuration snippet with basic auth
- job_name: 'clickhouse_exporter_basic_auth'
  basic_auth:
    username: 'exporter_user'
    password: 'exporter_password'
  static_configs:
    - targets: ['localhost:9100']
```

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

### Complete Exporter Usage Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

A full example demonstrating how to create, configure, and run the ClickHouse Exporter. It includes parsing the ClickHouse URL, creating the exporter instance, registering it with Prometheus, and exposing the metrics endpoint.

```Go
package main

import (
    "net/http"
    "net/url"
    
    "github.com/ClickHouse/clickhouse_exporter/exporter"
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

func main() {
    // Parse ClickHouse URL
    clickhouseURL, err := url.Parse("http://localhost:8123/")
    if err != nil {
        panic(err)
    }
    
    // Create exporter with no authentication
    exp := exporter.NewExporter(*clickhouseURL, true, "", "")
    
    // Register with default Prometheus registry
    prometheus.MustRegister(exp)
    
    // Expose metrics endpoint
    http.Handle("/metrics", promhttp.Handler())
    http.ListenAndServe(":9116", nil)
}
```

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

### Local Development Setup with Docker Compose

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/CONTRIBUTING.md

Use Docker Compose to bring up the development environment. Then, initialize dependencies and build the project.

```bash
docker-compose up
```

```bash
make init
```

```bash
make
```

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

### Start ClickHouse Exporter

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/README.md

Starts the ClickHouse Exporter with a specified ClickHouse scrape URI and telemetry address.

```bash
./clickhouse_exporter -scrape_uri=http://clickhouse-server:8123/ -telemetry.address=:9116
```

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

### Start ClickHouse Exporter Locally

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/00-START-HERE.md

Run the exporter with default settings to expose metrics on http://localhost:9116/metrics.

```bash
./clickhouse_exporter
# Listens on http://localhost:9116/metrics
```

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

### Usage Example for telemetry.address

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Demonstrates how to set the -telemetry.address flag to listen on a specific interface and port.

```bash
./clickhouse_exporter -telemetry.address=0.0.0.0:9116
```

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

### Usage Example for telemetry.endpoint

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Shows how to use the -telemetry.endpoint flag to specify a custom path for metrics and how to access them.

```bash
./clickhouse_exporter -telemetry.endpoint=/prometheus
# Metrics available at: http://localhost:9116/prometheus
```

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

### CLI Usage Patterns

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

Examples of how to use the ClickHouse Exporter via its command-line interface. These cover various configuration options and startup scenarios.

```bash
# Basic usage with default configuration
./clickhouse_exporter

# Specify ClickHouse host and port
./clickhouse_exporter --clickhouse.host=localhost --clickhouse.port=9000

# Specify listen address and port for the exporter
./clickhouse_exporter --web.listen-address=:9100

# Enable TLS for the exporter's HTTP server
./clickhouse_exporter --web.listen-address=:9100 --web.tls-cert-file=/path/to/cert.pem --web.tls-key-file=/path/to/key.pem

# Set a custom scrape interval for Prometheus
./clickhouse_exporter --scrape.interval=30s

# Configure authentication for ClickHouse
./clickhouse_exporter --clickhouse.user=user --clickhouse.password=password

# Use a specific ClickHouse configuration file
./clickhouse_exporter --config.file=/etc/clickhouse-exporter/config.yml

# Enable debug logging
./clickhouse_exporter --log.level=debug
```

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

### Info Log Output Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

An example of an informational log message generated by the exporter, including the message content and timestamp.

```json
{"level":"info","message":"Scraping http://localhost:8123/","time":"2024-01-15T10:30:45Z"}
```

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

### Example Usage of Insecure Flag

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Demonstrates how to use the `-insecure` flag with different values for development and production environments.

```bash
# Self-signed certificate (development)
./clickhouse_exporter \
  -scrape_uri=https://clickhouse.test:8443/ \
  -insecure=true
```

```bash
# Properly signed certificate (production)
./clickhouse_exporter \
  -scrape_uri=https://clickhouse.prod:8443/ \
  -insecure=false
```

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

### Start ClickHouse Exporter

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/00-START-HERE.md

Set environment variables for authentication and then run the exporter with the scrape URI. Ensure ClickHouse is accessible at the specified address.

```bash
export CLICKHOUSE_USER=admin
export CLICKHOUSE_PASSWORD=secret
./clickhouse_exporter -scrape_uri=http://clickhouse:8123/
```

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

### Usage Example for scrape_uri

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Demonstrates setting the -scrape_uri flag to point to a remote or production ClickHouse instance.

```bash
./clickhouse_exporter -scrape_uri=http://clickhouse-prod:8123/
```

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

### Fatal Log Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/errors.md

Illustrates a fatal log message, typically indicating startup configuration errors that cause the exporter to exit immediately.

```json
{"level":"fatal","error":"parse clickhouse.example.com: no such host","time":"2024-01-15T10:30:45Z","message":""}
```

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

### Fatal Log Output Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

An example of a fatal log message, indicating an error such as a network address being already in use, along with the timestamp.

```json
{"level":"fatal","error":"listen tcp :9116: bind: address already in use","time":"2024-01-15T10:30:46Z"}
```

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

### Exporter Registration Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Demonstrates the typical usage of the Exporter within a Prometheus registration flow. Prometheus automatically calls the Describe method during this process.

```go
exporter := exporter.NewExporter(*url, true, "", "")
prometheus.MustRegister(exporter)
// Prometheus will call Describe internally during registration
```

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

### Usage Examples for clickhouse_only Flag

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Illustrates the default behavior of exposing all metrics and how to use the -clickhouse_only flag to expose only ClickHouse metrics.

```bash
# Default: include Go runtime and client library metrics
./clickhouse_exporter

# Only ClickHouse metrics
./clickhouse_exporter -clickhouse_only
```

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

### Example Invalid Key-Value Response Error

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/errors.md

An example error message for an invalid key-value response format, indicating an unexpected line number and content.

```text
parseKeyValueResponse: unexpected 5 line: InvalidMetricFormat WithThreeFields
```

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

### Combined Configuration with Authentication and Custom Endpoint

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

A comprehensive example combining multiple flags for authentication, custom scrape URI, telemetry address, telemetry endpoint, and insecure HTTPS connection.

```bash
export CLICKHOUSE_USER=admin
export CLICKHOUSE_PASSWORD=secret
./clickhouse_exporter \
  -scrape_uri=https://ch-prod.internal:8443/ \
  -telemetry.address=0.0.0.0:9116 \
  -telemetry.endpoint=/metrics \
  -insecure=true
```

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

### Exporter Collect Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Demonstrates how to use the Exporter's Collect method within an HTTP handler or Prometheus scrape cycle. It initializes the exporter, collects metrics into a channel, and then processes them.

```go
// In HTTP handler or Prometheus scrape cycle
exporter := exporter.NewExporter(*url, true, "", "")
metricsCh := make(chan prometheus.Metric)

go func() {
    exporter.Collect(metricsCh)
    close(metricsCh)
}()

// Process metrics
for m := range metricsCh {
    fmt.Println(m)
}
```

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

### GET /

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Serves a simple HTML page at the root path. This page acts as a basic health check and provides a link to the metrics endpoint.

```APIDOC
## GET /

### Description
Serves a simple HTML page at the root path. This page acts as a basic health check and provides a link to the metrics endpoint.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **Content-Type**: text/html

#### Response Example
```html
<html>
    <head><title>Clickhouse Exporter</title></head>
    <body>
    <h1>Clickhouse Exporter</h1>
    <p><a href="/metrics">Metrics</a></p>
    </body>
    </html>
```
```

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

### Run ClickHouse Exporter

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Set ClickHouse credentials using environment variables and start the exporter with specified scrape and telemetry addresses. Verify the exporter is running by curling its metrics endpoint.

```bash
# Set ClickHouse credentials
export CLICKHOUSE_USER=admin
export CLICKHOUSE_PASSWORD=secret

# Start exporter
./clickhouse_exporter \
  -scrape_uri=https://clickhouse-prod:8443/ \
  -telemetry.address=0.0.0.0:9116 \
  -telemetry.endpoint=/metrics \
  -insecure=false

# In another terminal, verify it's working
curl http://localhost:9116/
curl http://localhost:9116/metrics | head -20
```

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

### Run ClickHouse Exporter using Docker

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/README.md

Start the ClickHouse Exporter as a detached Docker container, exposing port 9116 and specifying the ClickHouse scrape URI.

```bash
docker run -d -p 9116:9116 clickhouse-exporter -scrape_uri=http://clickhouse-url:8123/
```

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

### Collect Metrics Only from ClickHouse

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/README.md

Starts the ClickHouse Exporter to collect metrics exclusively from ClickHouse, excluding exporter-specific metrics.

```bash
./clickhouse_exporter -clickhouse_only
```

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

### Info Log Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/errors.md

Shows an info log message, which is used for collection errors. These errors are logged when a collection attempt fails but do not cause the exporter to exit.

```json
{"level":"info","message":"Error scraping clickhouse: error scraping clickhouse url http://clickhouse:8123/?query=...: status 401 Unauthorized (401): DB::Exception: User default: Authentication failed","time":"2024-01-15T10:30:46Z"}
```

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

### Example HTTP Status Code Error Message

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/errors.md

An example of an error message indicating an HTTP status code error from ClickHouse, typically due to authentication failure or invalid queries.

```text
status 401 Unauthorized (401): Code 516. DB::Exception: User default: Authentication failed
```

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

### Main Function Orchestration

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

The main function orchestrates the startup of the ClickHouse Exporter application. It handles command-line flag parsing, configuration of the Prometheus registry, exporter registration, and HTTP server setup for exposing metrics.

```go
func main() {
	// Parse Flags
	flag.Parse()

	// Parse Scrape URI
	scrapeURI, err := url.Parse(viper.GetString("scrape_uri"))
	if err != nil {
		log.Fatalf("Error parsing scrape URI: %v", err)
	}

	log.Printf("ClickHouse scrape URI: %s", scrapeURI)

	var reg prometheus.Registerer
	var gatherer prometheus.Gatherer

	// Setup Registry
	if !viper.GetBool("clickhouse_only") {
		reg = prometheus.DefaultRegisterer
		gatherer = prometheus.DefaultGatherer
	} else {
		reg = prometheus.NewRegistry()
		gatherer = reg
	}

	// Create and Register Exporter
	exporter := NewExporter(scrapeURI, viper.GetBool("insecure"), viper.GetString("username"), viper.GetString("password"))
	if err := reg.Register(exporter); err != nil {
		log.Fatalf("Error registering exporter: %v", err)
	}

	// Setup HTTP Routes
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte(`<html>
    <head><title>Clickhouse Exporter</title></head>
    <body>
    <h1>Clickhouse Exporter</h1>
    <p><a href="/metrics">Metrics</a></p>
    </body>
    </html>`))
	})
	http.Handle(viper.GetString("telemetry.endpoint"), promhttp.HandlerFor(gatherer, promhttp.HandlerOpts{}))

	// Start HTTP Server
	log.Printf("Starting server on %s", viper.GetString("telemetry.address"))
	if err := http.ListenAndServe(viper.GetString("telemetry.address"), nil); err != nil {
		log.Fatalf("Error starting server: %v", err)
	}
}
```

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

### GET /

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/endpoints.md

Provides a health check and information page. It returns a simple HTML page with a link to the metrics endpoint and does not require any metrics from ClickHouse to be available.

```APIDOC
## GET /

### Description
Health check and information page. Returns a simple HTML page with a link to the metrics endpoint. This endpoint is always available and does not require metrics from ClickHouse.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200 OK)
- **Content-Type**: text/html
- **Body**: Simple HTML page with title "Clickhouse Exporter" and a link to the metrics endpoint

### Request Example
```bash
curl http://localhost:9116/
```

### Response Example
```html
<html>
  <head><title>Clickhouse Exporter</title></head>
  <body>
    <h1>Clickhouse Exporter</h1>
    <p><a href="/metrics">Metrics</a></p>
  </body>
</html>
```
```

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

### Invalid Scrape URI Startup Error

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/errors.md

This error occurs during application initialization if the -scrape-uri flag contains an unparseable URL. The program will log a fatal error and exit without starting the HTTP server. Ensure the URL is a valid HTTP or HTTPS URL with a scheme and host.

```bash
./clickhouse_exporter -scrape_uri="not-a-valid-url"
```

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

### Run ClickHouse Exporter with Boolean Flag

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

Example of running the ClickHouse exporter with a boolean flag enabled. Boolean flags like '-clickhouse_only' can be specified without a value to set them to true.

```bash
# Also valid (boolean flag without value)
./clickhouse_exporter -clickhouse_only
```

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

### Go: Handle HTTP Response from ClickHouse

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Makes an HTTP GET request to a given URI, handles authentication headers (X-ClickHouse-User, X-ClickHouse-Key), and checks for error status codes. It returns the response body as a byte slice or an error.

```go
func (e *Exporter) handleResponse(uri string) ([]byte, error) {
	// ... implementation details ...
	return nil, nil
}
```

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

### GET /metrics

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Exposes Prometheus metrics collected from ClickHouse. This endpoint is crucial for monitoring the exporter's performance and the state of ClickHouse.

```APIDOC
## GET /metrics

### Description
Exposes Prometheus metrics collected from ClickHouse. This endpoint is crucial for monitoring the exporter's performance and the state of ClickHouse.

### Method
GET

### Endpoint
/metrics (or custom path defined by -telemetry.endpoint flag)

### Response
#### Success Response (200)
- **Content-Type**: text/plain; version=0.0.4; charset=utf-8 (or gzip-encoded if client requests)

### Purpose
Exposes Prometheus metrics

### Implementation
- Uses Prometheus client library's HTTP handler
- Calls `Collect()` on registered collectors (including Exporter)
- Returns metrics in Prometheus text exposition format
- Handles gzip compression if client requests it
```

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

### GET /metrics

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/endpoints.md

Exposes Prometheus metrics in a text-based format. The actual path can be configured. It includes various ClickHouse and exporter-specific metrics, and handles errors by indicating exporter health.

```APIDOC
## GET /metrics (default path)

### Description
Prometheus metrics endpoint. Returns all collected metrics in Prometheus exposition format (text-based). The actual path is configurable via the `-telemetry.endpoint` flag.

### Method
GET

### Endpoint
/metrics

### Parameters
#### Query Parameters
- **-telemetry.endpoint** (string) - Optional - Configurable path for the metrics endpoint.

### Response
#### Success Response (200 OK)
- **Content-Type**: text/plain; version=0.0.4; charset=utf-8
- **Body**: Prometheus format metrics (text)

### Request Example
```bash
curl http://localhost:9116/metrics
```

### Response Example
```
# HELP ClickHouseMetrics_DictCacheRequests Number of DictCacheRequests currently processed
# TYPE ClickHouseMetrics_DictCacheRequests gauge
ClickHouseMetrics_DictCacheRequests 0

# HELP ClickHouseAsyncMetrics_AsynchronousMetricsUpdateMS Number of AsynchronousMetricsUpdateMS async processed
# TYPE ClickHouseAsyncMetrics_AsynchronousMetricsUpdateMS gauge
ClickHouseAsyncMetrics_AsynchronousMetricsUpdateMS 145

# HELP ClickHouseEvents_Query_total Number of Query total processed
# TYPE ClickHouseEvents_Query_total counter
ClickHouseEvents_Query_total 42

# HELP ClickHouseParts_TablePartsBytes Table size in bytes
# TYPE ClickHouseParts_TablePartsBytes gauge
ClickHouseParts_TablePartsBytes{database="default",table="events"} 1048576

# HELP ClickHouseDisks_FreeSpaceInBytes Disks free_space_in_bytes capacity
# TYPE ClickHouseDisks_FreeSpaceInBytes gauge
ClickHouseDisks_FreeSpaceInBytes{disk="default"} 107374182400

# HELP ClickHouseExporter_ScrapeFailuresTotal Number of errors while scraping clickhouse.
# TYPE ClickHouseExporter_ScrapeFailuresTotal counter
ClickHouseExporter_ScrapeFailuresTotal 0

# HELP up Was the last query of ClickHouse successful.
# TYPE up gauge
up 1
```
```

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

### Invalid Flag Usage Example

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

Illustrates an invalid command-line flag usage where a flag appears after positional arguments. The exporter expects flags to precede any positional arguments.

```bash
# Invalid (flag after positional argument - but no positional args are expected)
```

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

### Prometheus Scrape Configuration

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/endpoints.md

Configure Prometheus to scrape metrics from the ClickHouse exporter. Ensure the target address and ports match your exporter setup. Adjust scrape_interval and scrape_timeout as needed for your environment.

```yaml
scrape_configs:
  - job_name: 'clickhouse'
    static_configs:
      - targets: ['localhost:9116']
    scrape_interval: 30s
    scrape_timeout: 10s
```

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

### Example Invalid Numeric Value Error Message

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/errors.md

An example error message indicating that a value expected to be numeric could not be parsed, typically due to invalid syntax.

```text
strconv.ParseFloat: parsing "not_a_number": invalid syntax
```

```text
strconv.Atoi: parsing "not_a_number": invalid syntax
```

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

### Display ClickHouse Exporter Help

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/README.md

View available flags and options for the ClickHouse Exporter by running the help command.

```bash
./clickhouse_exporter --help
```

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

### Exporter Implementation Details

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

Provides a glimpse into the core implementation of the Exporter, likely involving metric collection and processing logic. This snippet is part of the `exporter/exporter.go` file.

```go
func (e *Exporter) Describe(ch chan<- *prometheus.Desc) {
	// Implementation details for describing metrics
}

func (e *Exporter) Collect(ch chan<- prometheus.Metric) {
	// Implementation details for collecting metrics
}
```

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

### Main Application API

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/_DELIVERY_SUMMARY.txt

Documentation for the Main application API, covering CLI flags, environment variables, the main function, and HTTP routes.

```APIDOC
## Main Application API

### Description
Details the main application's public interface, including command-line flags, environment variables, and exposed HTTP routes.

### Audience
Operators and developers understanding the application's startup flow.

### Content
CLI flags, environment variables, main function, HTTP routes.
```

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

### Build Docker Image for ClickHouse Exporter

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/README.md

Create a Docker image named 'clickhouse-exporter' from the current directory's Dockerfile.

```bash
docker build . -t clickhouse-exporter
```

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

### ClickHouse Exporter CLI Usage

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/00-START-HERE.md

Demonstrates how to run the ClickHouse Exporter from the command line. Flags control the telemetry address, metrics path, ClickHouse connection URI, and security settings. Environment variables can also be used for credentials.

```bash
./clickhouse_exporter [flags]

Flags:
  -telemetry.address    Listen address (:9116)
  -telemetry.endpoint   Metrics path (/metrics)
  -scrape_uri           ClickHouse URL (http://localhost:8123/)
  -clickhouse_only      Metrics only (false)
  -insecure             Skip cert validation (true)

Env:
  CLICKHOUSE_USER       Username
  CLICKHOUSE_PASSWORD   Password
```

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

### NewExporter Constructor

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Creates and initializes a new Exporter instance. Use this to set up metric collection from a ClickHouse endpoint, optionally with authentication and TLS configuration.

```go
func NewExporter(uri url.URL, insecure bool, user, password string) *Exporter
```

```go
package main

import (
    "net/url"
    "github.com/ClickHouse/clickhouse_exporter/exporter"
)

func main() {
    // Parse the ClickHouse endpoint URL
    baseURL, err := url.Parse("http://clickhouse-server:8123/")
    if err != nil {
        panic(err)
    }
    
    // Create exporter with authentication
    exp := exporter.NewExporter(
        *baseURL,
        true,  // insecure: skip cert validation (OK for testing)
        "admin",  // username
        "password",  // password
    )
    
    // Now register with Prometheus and use in HTTP handler
    prometheus.MustRegister(exp)
}
```

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

### Run ClickHouse Exporter

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/README.md

Execute the ClickHouse Exporter with optional flags. Ensure you have the executable available.

```bash
./clickhouse_exporter [flags]
```

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

### NewExporter Constructor

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Creates and initializes a new Exporter instance for collecting ClickHouse metrics. It configures the necessary URIs, an HTTP client with a timeout and TLS settings, and initializes a Prometheus counter for scrape failures. Credentials can be provided for HTTP authentication.

```APIDOC
## NewExporter Constructor

### Description
Creates and initializes a new Exporter instance for collecting ClickHouse metrics. It configures the necessary URIs, an HTTP client with a timeout and TLS settings, and initializes a Prometheus counter for scrape failures. Credentials can be provided for HTTP authentication.

### Signature
```go
func NewExporter(uri url.URL, insecure bool, user, password string) *Exporter
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `uri` | `url.URL` | Yes | — | Base URI of the ClickHouse HTTP endpoint (e.g., `http://localhost:8123/`). Must be a valid URL; typically created with `url.Parse()`. The scheme (http/https) and host are required; path and query parameters are preserved |
| `insecure` | `bool` | Yes | — | If true, skip TLS certificate validation for HTTPS connections. If false, strictly validate certificates. Pass `true` for self-signed or test certificates |
| `user` | `string` | No | empty string | ClickHouse username for HTTP authentication. Sent via the `X-ClickHouse-User` header. If empty and `password` is empty, no authentication header is sent |
| `password` | `string` | No | empty string | ClickHouse password for HTTP authentication. Sent via the `X-ClickHouse-Key` header. Only used if `user` is also non-empty |

### Return Type
`*Exporter` - A pointer to an initialized Exporter instance

### Behavior
1. Parses the base `uri` to construct five query URIs:
   - `metricsURI`: Appends query `select metric, value from system.metrics`
   - `asyncMetricsURI`: Appends query with metric name normalization from `system.asynchronous_metrics`
   - `eventsURI`: Appends query `select event, value from system.events`
   - `partsURI`: Appends query `select database, table, sum(bytes) as bytes, count() as parts, sum(rows) as rows from system.parts where active = 1 group by database, table`
   - `disksMetricURI`: Appends query `select name, sum(free_space) as free_space_in_bytes, sum(total_space) as total_space_in_bytes from system.disks group by name`

2. Creates an HTTP client with:
   - 30-second timeout
   - TLS configuration based on `insecure` flag
   - Ready for making requests to ClickHouse

3. Initializes the `scrapeFailures` counter metric for tracking errors

4. Stores credentials for use in subsequent HTTP requests

### Throws
None - Does not validate the URL format at construction time (invalid URL causes error when collecting metrics)

### Example
```go
package main

import (
    "net/url"
    "github.com/ClickHouse/clickhouse_exporter/exporter"
)

func main() {
    // Parse the ClickHouse endpoint URL
    baseURL, err := url.Parse("http://clickhouse-server:8123/")
    if err != nil {
        panic(err)
    }
    
    // Create exporter with authentication
    exp := exporter.NewExporter(
        *baseURL,
        true,  // insecure: skip cert validation (OK for testing)
        "admin",  // username
        "password",  // password
    )
    
    // Now register with Prometheus and use in HTTP handler
    prometheus.MustRegister(exp)
}
```
```

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

### Connect to Remote ClickHouse with Authentication

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/00-START-HERE.md

Configure user and password for connecting to a remote ClickHouse instance. Ensure CLICKHOUSE_USER and CLICKHOUSE_PASSWORD environment variables are set.

```bash
export CLICKHOUSE_USER=myuser
export CLICKHOUSE_PASSWORD=mypass
./clickhouse_exporter -scrape_uri=http://clickhouse-server:8123/
```

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

### NewExporter Function Usage

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

Demonstrates how to instantiate a new ClickHouse Exporter using the `NewExporter` function in Go. This is typically used when integrating the exporter into a larger application.

```go
exporter, err := NewExporter(ExporterConfig{
	ClickHouseHost: "localhost",
	ClickHousePort: 9000,
	ScrapeInterval: 30 * time.Second,
})
if err != nil {
	log.Fatal(err)
}
```

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

### Handle Server Listen Error

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Logs any error from http.ListenAndServe using zerolog and exits immediately. Common causes include the port being already in use or permission issues.

```go
log.Fatal().Err(http.ListenAndServe(*listeningAddress, nil)).Send()
```

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

### Configure Custom Metrics Endpoint Path

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/endpoints.md

Use the -telemetry.endpoint flag to set a custom path for the metrics endpoint. Metrics will then be available at the specified path.

```bash
./clickhouse_exporter -telemetry.endpoint=/prometheus
```

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

### Go Module Definition

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/MANIFEST.md

The `go.mod` file defines the module path and its dependencies. This is essential for Go's build system to manage the project's modules.

```go
module github.com/hyperdxio/clickhouse_exporter

go 1.21

require (
	github.com/prometheus/client_golang v1.20.5
	github.com/rs/zerolog v1.33.0
)
```

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

### Exporter Type Definition and Constructor

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/00-START-HERE.md

Defines the main Exporter type and its constructor. Use `NewExporter` to create an exporter instance, providing connection details for ClickHouse.

```go
type Exporter struct { ... }

func NewExporter(uri url.URL, insecure bool, user, password string) *Exporter
func (e *Exporter) Collect(ch chan<- prometheus.Metric)
func (e *Exporter) Describe(ch chan<- *prometheus.Desc)
```

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

### Expose Metrics on a Custom Port

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

Configures the exporter to expose its metrics on a custom port. Use the -telemetry.address flag to set the desired port.

```bash
./clickhouse_exporter -telemetry.address=:9117
```

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

### Set ClickHouse Credentials via Environment Variables

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/README.md

Configure ClickHouse username and password for the exporter using environment variables if default credentials are not used.

```bash
CLICKHOUSE_USER
CLICKHOUSE_PASSWORD
```

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

### Prometheus Metrics Endpoint

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/endpoints.md

Access this endpoint to retrieve collected metrics in Prometheus exposition format. The path is configurable. It includes ClickHouse system metrics, partition info, disk space, and exporter health status.

```bash
curl http://localhost:9116/metrics
```

```text
# HELP ClickHouseMetrics_DictCacheRequests Number of DictCacheRequests currently processed
# TYPE ClickHouseMetrics_DictCacheRequests gauge
ClickHouseMetrics_DictCacheRequests 0

# HELP ClickHouseAsyncMetrics_AsynchronousMetricsUpdateMS Number of AsynchronousMetricsUpdateMS async processed
# TYPE ClickHouseAsyncMetrics_AsynchronousMetricsUpdateMS gauge
ClickHouseAsyncMetrics_AsynchronousMetricsUpdateMS 145

# HELP ClickHouseEvents_Query_total Number of Query total processed
# TYPE ClickHouseEvents_Query_total counter
ClickHouseEvents_Query_total 42

# HELP ClickHouseParts_TablePartsBytes Table size in bytes
# TYPE ClickHouseParts_TablePartsBytes gauge
ClickHouseParts_TablePartsBytes{database="default",table="events"} 1048576

# HELP ClickHouseDisks_FreeSpaceInBytes Disks free_space_in_bytes capacity
# TYPE ClickHouseDisks_FreeSpaceInBytes gauge
ClickHouseDisks_FreeSpaceInBytes{disk="default"} 107374182400

# HELP ClickHouseExporter_ScrapeFailuresTotal Number of errors while scraping clickhouse.
# TYPE ClickHouseExporter_ScrapeFailuresTotal counter
ClickHouseExporter_ScrapeFailuresTotal 0

# HELP up Was the last query of ClickHouse successful.
# TYPE up gauge
up 1
```

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

### Prometheus Metrics Endpoint

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Exposes Prometheus metrics in the standard text exposition format. This endpoint handles metric collection and supports gzip compression if requested by the client.

```go
promhttp.HandlerFor(gatherer, promhttp.HandlerOpts{})
```

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

### Go: Parse Disk Response from ClickHouse

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Parses the ClickHouse system.disks response, which includes three columns: disk name, free space, and total space. Returns a slice of diskResult or an error.

```go
func (e *Exporter) parseDiskResponse(uri string) ([]diskResult, error) {
	// ... implementation details ...
	return nil, nil
}
```

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

### Connect to HTTPS with Certificate Validation

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

Connects to an HTTPS ClickHouse endpoint and enables certificate validation. Ensure -insecure is set to false or omitted.

```bash
./clickhouse_exporter \
  -scrape_uri=https://clickhouse.example.com:8443/ \
  -insecure=false
```

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

### Root HTML Page

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Provides a simple HTML page for health checks and navigation to the metrics endpoint. This is served at the root path '/'.

```html
<html>
    <head><title>Clickhouse Exporter</title></head>
    <body>
    <h1>Clickhouse Exporter</h1>
    <p><a href="/metrics">Metrics</a></p>
    </body>
    </html>
```

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

### Go: ClickHouse Exporter Collect Method

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

The core collection logic that queries ClickHouse system tables, parses responses into metrics, converts them to Prometheus metric objects, and sends them to a channel. It returns an error if any query fails.

```go
func (e *Exporter) collect(ch chan<- prometheus.Metric) error {
	// ... implementation details ...
	return nil
}
```

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

### Configure Prometheus to Scrape ClickHouse Exporter

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/INDEX.md

Add the provided configuration to your prometheus.yml file to enable Prometheus to scrape metrics from the ClickHouse Exporter.

```yaml
scrape_configs:
  - job_name: 'clickhouse'
    static_configs:
      - targets: ['localhost:9116']
    scrape_interval: 30s
```

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

### Prometheus Collector Interface Compliance

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Demonstrates the Exporter type's compliance with the Prometheus Collector interface, ensuring it can be integrated with Prometheus for metric collection.

```Go
type Collector interface {
    Describe(chan<- *prometheus.Desc)
    Collect(chan<- prometheus.Metric)
}

var _ prometheus.Collector = (*Exporter)(nil)
```

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

### Connect to Remote ClickHouse Server

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/configuration.md

Connects the exporter to a ClickHouse server running on a different host. Specify the ClickHouse URI using the -scrape_uri flag.

```bash
./clickhouse_exporter -scrape_uri=http://clickhouse.example.com:8123/
```

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

### Handle URL Parse Error

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Parses the ClickHouse scrape URI. Logs any parsing error using zerolog and exits immediately.

```go
uri, err := url.Parse(*clickhouseScrapeURI)
if err != nil {
    log.Fatal().Err(err).Send()
}
```

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

### Verify ClickHouse Reachability and Exporter URI

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/INDEX.md

Check if ClickHouse is running and accessible using curl. Verify the exporter's scrape URI points to the correct ClickHouse instance.

```bash
# Check if ClickHouse is running
curl http://localhost:8123/?query=SELECT%201

# Verify exporter URI
./clickhouse_exporter -scrape_uri=http://clickhouse-server:8123/
```

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

### Go: Parse Key-Value Response from ClickHouse

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Parses ClickHouse HTTP responses that have a two-column format (key and numeric value). This is used for metrics like system.metrics, system.asynchronous_metrics, and system.events.

```go
func (e *Exporter) parseKeyValueResponse(uri string) ([]lineResult, error) {
	// ... implementation details ...
	return nil, nil
}
```

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

### Prometheus Configuration for ClickHouse Exporter

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/00-START-HERE.md

Configure Prometheus to scrape metrics from the ClickHouse Exporter. Ensure the exporter is running and accessible at the specified target address.

```yaml
scrape_configs:
  - job_name: 'clickhouse'
    static_configs:
      - targets: ['localhost:9116']
```

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

### Retrieve Exporter Metrics

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/README.md

Fetches the metrics exposed by the ClickHouse Exporter via its /metrics endpoint.

```bash
curl http://localhost:9116/metrics
```

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

### Setting ClickHouse Password via Environment Variable

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Configure the ClickHouse password for HTTP authentication by setting the CLICKHOUSE_PASSWORD environment variable. This variable is only used if CLICKHOUSE_USER is also set.

```bash
export CLICKHOUSE_USER=myuser
export CLICKHOUSE_PASSWORD=mypassword
./clickhouse_exporter
```

```go
var password = os.Getenv("CLICKHOUSE_PASSWORD")
```

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

### Setting ClickHouse User via Environment Variable

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/main.md

Configure the ClickHouse username for HTTP authentication by setting the CLICKHOUSE_USER environment variable. This is used in conjunction with CLICKHOUSE_PASSWORD to add authentication headers.

```bash
export CLICKHOUSE_USER=myuser
./clickhouse_exporter
```

```go
var user = os.Getenv("CLICKHOUSE_USER")
```

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

### Check Exporter Health

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/00-START-HERE.md

Verify the exporter is running and accessible by checking the '/metrics' endpoint. A 'up 1' output indicates success, while 'up 0' indicates failure.

```bash
curl http://localhost:9116/metrics | grep '^up '
# Shows: up 1 (success) or up 0 (failure)
```

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

### Exporter.Describe

Source: https://github.com/hyperdxio/clickhouse_exporter/blob/master/_autodocs/api-reference/exporter.md

Describes all metrics that the Exporter will produce. This method implements the prometheus.Collector.Describe() interface.

```APIDOC
## Exporter.Describe

### Description
Describes all metrics that the Exporter will produce. Implements `prometheus.Collector.Describe()`.

### Signature
```go
func (e *Exporter) Describe(ch chan<- *prometheus.Desc)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **ch** (`chan<- *prometheus.Desc`) - Required - Channel to send metric descriptors to. Must be open and ready to receive

### Behavior
1. Uses the "poor man's Describe" pattern: runs Collect in a goroutine and extracts descriptor information from the resulting metrics
2. Creates a channel for metrics and a done channel for synchronization
3. Spawns a goroutine to read metrics and send their descriptors to the provided channel
4. Calls `Collect()` internally, which actually gathers the metrics
5. Closes the metrics channel and waits for the goroutine to finish
6. Returns when all descriptors have been sent

### Implementation Detail
Because ClickHouse metrics are dynamic (unknown at startup), this method cannot predict which metrics will be collected. Instead, it collects them once and uses their descriptors. This is less efficient than a static descriptor list but necessary for this use case.

### Example
```go
// Typical usage in Prometheus registration flow
exporter := exporter.NewExporter(*url, true, "", "")
prometheus.MustRegister(exporter)
// Prometheus will call Describe internally during registration
```
```