Merge pull request #13 from armitageee/develop

feat: [ add tracing ]

Author: armitageee

.env.example

@@ -1,52 +1,35 @@
-# FACEIT API Key
-# Get your API key from: https://developers.faceit.com/
-FACEIT_API_KEY=your_api_key_here
+# FACEIT API Configuration
+FACEIT_API_KEY=your_faceit_api_key_here
 
-# Default player nickname (optional)
-# If set, this player will be loaded automatically on startup
-FACEIT_DEFAULT_PLAYER=your_nickname_here
+# Optional: Default player nickname
+FACEIT_DEFAULT_PLAYER=
 
-# Logging configuration
-# Log level: debug, info, warn, error (default: info)
+# Logging Configuration
 LOG_LEVEL=info
+LOG_TO_STDOUT=true
+PRODUCTION_MODE=false
 
-# Kafka configuration
-# Enable Kafka logging (default: false)
+# Kafka Configuration (optional)
 KAFKA_ENABLED=false
-
-# Kafka brokers (comma-separated, default: localhost:9092)
 KAFKA_BROKERS=localhost:9092
-
-# Kafka topic for logs (default: faceit-cli-logs)
 KAFKA_TOPIC=faceit-cli-logs
 
-# Production mode settings
-# Enable production mode (default: false)
-PRODUCTION_MODE=false
-
-# Log to stdout (default: true, set to false in production)
-LOG_TO_STDOUT=true
-
-# Pagination settings
-# Matches per page (default: 10)
+# Pagination Configuration
 MATCHES_PER_PAGE=10
-
-# Maximum matches to load (default: 100)
 MAX_MATCHES_TO_LOAD=100
+COMPARISON_MATCHES=20
 
-# Cache settings
-# Enable caching (default: false)
+# Cache Configuration
 CACHE_ENABLED=false
-
-# Cache TTL in minutes (default: 30)
 CACHE_TTL=30
 
-# Comparison settings
-# Number of matches to use for player comparison (default: 20)
-COMPARISON_MATCHES=20
+# Telemetry Configuration
+TELEMETRY_ENABLED=true
+OTLP_ENDPOINT=http://localhost:4318
+ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans
+SERVICE_NAME=faceit-cli
+SERVICE_VERSION=1.0.0
+ENVIRONMENT=development
 
-# Match Search Features
-# - Search matches by ID from main menu (press '2')
-# - Paste match IDs with Ctrl+V, Cmd+V, F2, or P
-# - View detailed team statistics for any match
-# - Cross-platform clipboard support (macOS, Linux, Windows)
+# Suppress OpenTelemetry logs to avoid stdout pollution
+OTEL_LOG_LEVEL=info

.gitignore

@@ -40,3 +40,6 @@ Thumbs.db
 # Coverage
 coverage.out
 coverage.html
+
+/bazel-*
+WARP.md

Makefile

@@ -196,6 +196,18 @@ run-optimized:
 	@echo "Running with all optimizations..."
 	CACHE_ENABLED=true CACHE_TTL=30 MATCHES_PER_PAGE=10 MAX_MATCHES_TO_LOAD=50 go run main.go
 
+# Initialize configuration
+.PHONY: init
+init:
+	@echo "Initializing configuration..."
+	@go run main.go init
+
+# Install via go install
+.PHONY: install
+install:
+	@echo "Installing faceit-cli via go install..."
+	@go install github.com/armitageee/faceit-cli@latest
+
 # Help
 .PHONY: help
 help:
@@ -213,6 +225,8 @@ help:
 	@echo "  clean         - Clean build artifacts"
 	@echo "  deps          - Install dependencies"
 	@echo "  install-tools - Install development tools"
+	@echo "  init          - Initialize configuration file"
+	@echo "  install       - Install via go install"
 	@echo "  docker-build  - Build Docker image"
 	@echo "  docker-run    - Run in Docker with .env file"
 	@echo "  run           - Build and run the application"

README.md

@@ -22,11 +22,27 @@ A beautiful terminal user interface (TUI) for viewing FACEIT player profiles and
 
 ## Quick Start
 
-### Option 1: Pre-built Binaries
+### Option 1: Go Install (Recommended)
+
+```bash
+# Install the latest version
+go install github.com/armitageee/faceit-cli@latest
+
+# Initialize configuration
+faceit-cli init
+
+# Edit the config file and add your API key
+# ~/.config/faceit-cli/config.yml
+
+# Run the application
+faceit-cli
+```
+
+### Option 2: Pre-built Binaries
 
 Download the latest release from the [Releases page](https://github.com/armitageee/faceit-cli/releases) and extract the binary for your platform.
 
-### Option 2: Docker
+### Option 3: Docker
 
 ```bash
 # Clone the repository
@@ -80,7 +96,45 @@ make run-production
 
 ## Configuration
 
-Create a `.env` file in the project root:
+### Configuration Priority
+
+The application uses a flexible configuration system with the following priority order:
+
+1. **Environment Variables** (highest priority)
+2. **YAML Configuration** (`~/.config/faceit-cli/config.yml`)
+3. **Default Values** (lowest priority)
+
+### YAML Configuration
+
+The application supports YAML configuration files for better user experience:
+
+```bash
+# Initialize default config
+faceit-cli init
+
+# Edit the config file
+# ~/.config/faceit-cli/config.yml
+```
+
+### Environment Variables Override
+
+Environment variables always take priority over YAML configuration. This is useful for:
+- Production deployments
+- CI/CD pipelines
+- Temporary overrides
+- Security-sensitive values
+
+**Example:**
+```bash
+# YAML config has: log_level: "info", cache_enabled: true
+# Environment variable overrides it:
+export LOG_LEVEL="debug"
+export CACHE_ENABLED="false"
+
+# Result: log_level="debug", cache_enabled=false
+```
+
+You can use environment variables or a `.env` file in the project root:
 
 ```bash
 # Required

config.example.yml

@@ -0,0 +1,35 @@
+# FACEIT CLI Configuration
+# Copy this file to ~/.config/faceit-cli/config.yml and configure your settings
+
+# Required: Your FACEIT API key
+api_key: "your_faceit_api_key_here"
+
+# Optional: Default player to load on startup
+default_player: ""
+
+# Logging settings
+log_level: "info"  # debug, info, warn, error
+log_to_stdout: false
+production_mode: false
+
+# Pagination settings
+matches_per_page: 10
+max_matches_to_load: 100
+comparison_matches: 20
+
+# Caching settings
+cache_enabled: true
+cache_ttl: 30  # minutes
+
+# Kafka integration (optional)
+kafka_enabled: false
+kafka_brokers: "localhost:9092"
+kafka_topic: "faceit-cli-logs"
+
+# Telemetry settings (optional)
+telemetry_enabled: false
+otlp_endpoint: "localhost:4317"
+service_name: "faceit-cli"
+service_version: "1.0.0"
+environment: "development"
+otel_log_level: "fatal"

docker-compose.yml

@@ -67,5 +67,51 @@ services:
       "
     restart: "no"
 
+  # OpenTelemetry Collector
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.95.0
+    container_name: faceit-cli-otel-collector
+    command: ["--config=/etc/otel-collector-config.yaml"]
+    volumes:
+      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
+    ports:
+      - "4317:4317"   # OTLP gRPC receiver
+      - "4318:4318"   # OTLP HTTP receiver
+      - "8888:8888"   # Prometheus metrics
+      - "8889:8889"   # Prometheus exporter metrics
+    depends_on:
+      - zipkin
+    environment:
+      - OTEL_RESOURCE_ATTRIBUTES=service.name=faceit-cli-collector,service.version=1.0.0
+
+  # Zipkin for trace visualization
+  zipkin:
+    image: openzipkin/zipkin:3.3
+    container_name: faceit-cli-zipkin
+    ports:
+      - "9411:9411"
+    environment:
+      - STORAGE_TYPE=mem
+      - MYSQL_HOST=zipkin-mysql
+      - MYSQL_USER=zipkin
+      - MYSQL_PASS=zipkin
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:9411/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  # Jaeger as alternative trace backend (optional)
+  # jaeger:
+  #   image: jaegertracing/all-in-one:1.55
+  #   container_name: faceit-cli-jaeger
+  #   ports:
+  #     - "16686:16686"  # Jaeger UI
+  #     - "14250:14250"  # Jaeger gRPC
+  #   environment:
+  #     - COLLECTOR_OTLP_ENABLED=true
+  #   profiles:
+  #     - jaeger
+
 volumes:
   kafka-data: