### Install AppLogger CLI via PowerShell

Source: https://github.com/zuccadev-labs/apploggers/blob/main/cli/README.md

Use the provided installation script for Windows environments.

```powershell
# Windows PowerShell
irm https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.ps1 | iex
```

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

### Install Apploggers on Linux

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Installs the Apploggers CLI on Linux by downloading the binary, making it executable, and moving it to the system's PATH. Verifies the installation by checking the version.

```bash
ARCH=$(dpkg --print-architecture 2>/dev/null || uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
VERSION="apploggers-vX.Y.Z"

curl -L \
  "https://github.com/zuccadev-labs/appLoggers/releases/download/${VERSION}/apploggers-linux-${ARCH}" \
  -o apploggers

chmod +x apploggers
sudo mv apploggers /usr/local/bin/
apploggers version --output json
```

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

### Install AppLogger CLI via Shell

Source: https://github.com/zuccadev-labs/apploggers/blob/main/cli/README.md

Use the provided installation script for Linux or macOS environments.

```bash
# Linux
curl -fsSL https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.sh | bash

# macOS
curl -fsSL https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.sh | bash
```

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

### AppLogger Usage Examples

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/architecture.md

Practical examples demonstrating automatic tag inference, TaggedLogger, timed metrics, and safe execution blocks.

```kotlin
// Tag inferido automáticamente
class PlayerController(private val logger: AppLogger) {
    fun onError(t: Throwable) = this.logE(logger, "Playback failed", throwable = t)
    fun onStart() = logger.logI("PLAYER", "Playback started")
}

// TaggedLogger — elimina repetición del tag
class PaymentRepository(logger: AppLogger) {
    private val log = logger.withTag("PaymentRepository")
    fun charge() {
        log.i("Charging card")
        log.e("Charge failed", ex)
        log.metric("charge_latency", 120.0, "ms")
    }
}

// timed — mide latencia automáticamente
val user = logger.timed("db_query_user", "ms", mapOf("table" to "users")) {
    userDao.findById(id)
}

// logCatching — captura y loguea excepciones sin try/catch
val result = logger.logCatching("NetworkClient", "fetch user") {
    api.getUser(id)
}

// loggerTag<T>() — para companion objects
class NetworkRepository(private val logger: AppLogger) {
    companion object { val TAG = loggerTag<NetworkRepository>() }
    fun fetch() = logger.logI(TAG, "Fetching data")
}
```

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

### Install Docker Desktop on macOS using Homebrew

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs Docker Desktop on macOS using Homebrew.

```bash
brew install --cask docker
```

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

### Install Docker Desktop on Windows using winget

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs Docker Desktop on Windows using the Windows Package Manager.

```powershell
winget install Docker.DockerDesktop
```

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

### Install and Verify Apploggers CLI

Source: https://context7.com/zuccadev-labs/apploggers/llms.txt

Commands to install the CLI on Linux, macOS, or Windows and verify the installation.

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.ps1 | iex

# Verificar instalación
apploggers version --output json
```

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

### Full Production AppLogger Configuration Example

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-guided-setup/references/config-reference.md

A comprehensive example demonstrating how to configure AppLogger for a production environment, including settings for endpoint, API key, environment, logging levels, batching, persistence, consent, data minimization, integrity, data limits, and remote configuration.

```kotlin
AppLoggerConfig.Builder()
    .endpoint(BuildConfig.LOGGER_URL)
    .apiKey(BuildConfig.LOGGER_KEY)
    .environment("production")
    .debugMode(false)
    .consoleOutput(false)
    .minLevel(LogMinLevel.INFO)
    .batchSize(20)
    .flushIntervalSeconds(30)
    .bufferOverflowPolicy(BufferOverflowPolicy.PRIORITY_AWARE)
    .offlinePersistenceMode(OfflinePersistenceMode.CRITICAL_ONLY)
    .deduplicationWindowMs(10_000)
    .breadcrumbCapacity(10)
    .defaultConsentLevel(ConsentLevel.STRICT)         // sin consentimiento por defecto
    .dataMinimizationEnabled(true)
    .integritySecret(BuildConfig.LOGGER_HMAC_SECRET)  // si HMAC está activo
    .dailyDataLimitMb(50)                              // si control de costos es necesario
    .remoteConfigEnabled(true)
    .remoteConfigIntervalSeconds(300)
    .build()
```

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

### Log Startup Lifecycle Events

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-instrumentation-design/references/event-taxonomy.md

Examples for logging application initialization status and critical startup failures.

```kotlin
// App inicializada correctamente
AppLoggerSDK.info("BOOT", "Application started", extra = mapOf(
    "cold_start" to true,
    "app_version" to BuildConfig.VERSION_NAME
))

// SDK inicializado
AppLoggerSDK.info("BOOT", "AppLogger initialized", extra = mapOf(
    "transport" to "supabase",
    "environment" to "production"
))

// Fallo crítico en startup
AppLoggerSDK.critical("BOOT", "Database initialization failed", throwable = e)
```

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

### Initialize and Use Android SDK

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Setup the SDK in the Application class and utilize logging, metrics, and session helpers.

```kotlin
// 1. Application.kt — inicializar una sola vez
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        val transport = SupabaseTransport(
            endpoint = BuildConfig.LOGGER_URL,
            apiKey = BuildConfig.LOGGER_KEY,
            networkAvailabilityProvider = androidNetworkAvailabilityProvider(this)
        )

        AppLoggerSDK.initialize(
            context = this,
            config = AppLoggerConfig.Builder()
                .endpoint(BuildConfig.LOGGER_URL)
                .apiKey(BuildConfig.LOGGER_KEY)
                .environment("production")          // filtra QA vs prod en Supabase
                .debugMode(BuildConfig.LOGGER_DEBUG)
                .consoleOutput(BuildConfig.LOGGER_DEBUG)
                .minLevel(LogMinLevel.INFO)          // descarta DEBUG en producción
                .batchSize(20)
                .flushIntervalSeconds(30)
                .build(),
            transport = transport
        )
    }
}

// 2. Declarar en AndroidManifest.xml
// <application android:name=".MyApp" ... >

// 3. Usar en cualquier lugar — fire-and-forget
AppLoggerSDK.error("PAYMENT", "Transaction failed", throwable)
AppLoggerSDK.info("PLAYER", "Playback started", extra = mapOf("content_id" to "movie_123"))
AppLoggerSDK.warn("NETWORK", "Slow response", throwable = e, anomalyType = "HIGH_LATENCY")
AppLoggerSDK.metric("screen_load_time", 1234.0, "ms", tags = mapOf("screen" to "Home"))

// 4. Extension functions — tag inferido automáticamente del nombre de clase
this.logE(logger, "Playback failed", throwable = e)    // tag → nombre de la clase actual
this.logW(logger, "Buffer low", anomalyType = "BUFFER_LOW")

// 5. Helpers avanzados
val result = logger.timed("db_query", "ms") { userDao.findById(id) }  // mide latencia
val data   = logger.logCatching("API", "fetch user") { api.getUser() } // captura excepciones
val log    = logger.withTag("PaymentRepository")                        // tag fijo para la clase
log.i("Charging card"); log.e("Charge failed", throwable = e)

// 6. Sesión e identidad
AppLoggerSDK.setAnonymousUserId(anonymousUUID)
AppLoggerSDK.newSession()                              // fuerza nueva sesión (login/logout)
AppLoggerSDK.addGlobalExtra("ab_test", "checkout_v2") // adjunta a todos los eventos
```

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

### Compile Apploggers from Source

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Clones the Apploggers repository, downloads dependencies, builds the CLI, and installs it to the system's PATH. Verifies the installation by checking the version.

```bash
git clone https://github.com/zuccadev-labs/appLoggers.git
cd appLoggers/cli
go mod download
go build -o apploggers ./cmd/applogger-cli
sudo mv apploggers /usr/local/bin/
apploggers version --output json
```

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

### Log a complete OperationTrace span

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-instrumentation-design/references/metric-guidelines.md

This example shows how to start, configure, and end an OperationTrace span, which automatically logs metrics like duration, throughput, and success status.

```kotlin
AppLoggerSDK.startTrace("api_call", "endpoint" to url)
    .withTimeout(5_000)
    .bytes(responseBytes.size.toLong())
    .end()
// → trace.api_call con duration_ms, throughput_mbps, success, timed_out (si aplica)
```

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

### Install act on Windows using winget

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs the 'act' tool, a GitHub Actions local runner, on Windows using winget.

```powershell
# Windows
winget install nektos.act
```

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

### AppLogger: Correct and Incorrect Logging Examples

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs-investigation/privacy-compliance.md

Demonstrates proper usage of AppLogger by avoiding PII in messages and focusing on technical details. Use the 'Bien' examples to log technical information and avoid the 'Mal' examples which include sensitive data.

```kotlin
// ❌ MAL — incluye PII en el mensaje
AppLogger.error("AUTH", "User john.doe@example.com failed to login")
```

```kotlin
// ✅ BIEN — solo información técnica
AppLogger.error("AUTH", "Login failed: invalid credentials", extra = mapOf("error_code" to 401))
```

```kotlin
// ❌ MAL — incluye contenido del mensaje de WebSocket (puede tener datos del usuario)
AppLogger.debug("WS", "Received: $rawWebSocketMessage")
```

```kotlin
// ✅ BIEN — solo el evento técnico
AppLogger.debug("WS", "Message received", extra = mapOf("size_bytes" to message.toByteArray().size))
```

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

### Install GitHub CLI on Windows using winget

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs the GitHub CLI tool on Windows using the Windows Package Manager.

```powershell
# Windows
winget install GitHub.cli
```

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

### Complete Class Example with Apploggers Metrics

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-instrumentation-design/references/metric-guidelines.md

This example demonstrates a `ContentRepository` class that utilizes `AppLogger` for various logging needs, including timed operations, catching exceptions, and tracking metrics like bitrate and buffering duration. Ensure the `AppLogger` is properly initialized and injected.

```kotlin
class ContentRepository(private val logger: AppLogger) {

    private val log = logger.withTag("ContentRepository")

    suspend fun loadContent(id: String): Content {
        return this.timed(logger, "content_load_time", "ms", mapOf("content_id" to id)) {
            val result = this.logCatching(logger, "load content $id") {
                api.getContent(id)
            }
            result ?: throw ContentNotFoundException(id)
        }
    }

    fun trackQuality(bitrate: Int, contentId: String) {
        log.metric("bitrate", bitrate.toDouble(), "kbps", mapOf("content_id" to contentId))
    }

    fun trackBuffering(durationMs: Long) {
        log.metric("buffer_time", durationMs.toDouble(), "ms")
    }
}
```

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

### Semantic Versioning (SemVer) Example

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs-investigation/investigation.md

Illustrates the Semantic Versioning format (MAJOR.MINOR.PATCH) and its common pre-release extensions, indicating stability and compatibility.

```plaintext
MAJOR.MINOR.PATCH[-PRERELEASE]

1.0.0         → Estable, API pública fija
1.1.0         → Nueva funcionalidad, backwards compatible
1.1.1         → Bugfix
2.0.0         → Breaking change en la API pública
1.0.0-alpha.1 → Pre-release, API puede cambiar
1.0.0-beta.1  → Feature-complete, en período de prueba
```

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

### Install JDK 17 on Windows using winget

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs Eclipse Temurin JDK 17 on Windows using the Windows Package Manager.

```powershell
winget install EclipseAdoptium.Temurin.17.JDK
```

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

### Install act on macOS using Homebrew

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs the 'act' tool, a GitHub Actions local runner, on macOS using Homebrew.

```bash
# macOS
brew install act
```

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

### Install GitHub CLI on macOS using Homebrew

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs the GitHub CLI tool on macOS using Homebrew.

```bash
# macOS
brew install gh
```

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

### Configure Gradle Dependencies

Source: https://context7.com/zuccadev-labs/apploggers/llms.txt

Setup instructions for JitPack repositories and AppLoggers dependencies in Android projects.

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

// app/build.gradle.kts
dependencies {
    // Core del logger (obligatorio)
    implementation("com.github.zuccadev-labs.appLoggers:logger-core:0.2.0-alpha.12")

    // Transporte Supabase (si tu backend es Supabase)
    implementation("com.github.zuccadev-labs.appLoggers:logger-transport-supabase:0.2.0-alpha.12")

    // Utilidades de testing
    testImplementation("com.github.zuccadev-labs.appLoggers:logger-test:0.2.0-alpha.12")
}

// Mapear secrets de local.properties a BuildConfig
android {
    buildFeatures { buildConfig = true }
    defaultConfig {
        val props = Properties().apply {
            val file = rootProject.file("local.properties")
            if (file.exists()) load(file.inputStream())
        }
        buildConfigField("String", "LOGGER_URL", "\"${props["APPLOGGER_URL"] ?: ""}\"")
        buildConfigField("String", "LOGGER_KEY", "\"${props["APPLOGGER_ANON_KEY"] ?: ""}\"")
        buildConfigField("Boolean", "LOGGER_DEBUG", "${props["APPLOGGER_DEBUG"] ?: false}")
    }
}
```

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

### Install JDK 17 on macOS using Homebrew

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Installs Eclipse Temurin JDK 17 on macOS using Homebrew.

```bash
brew install --cask temurin@17
```

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

### Install AppLoggers CLI on Windows

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Installs the latest release of the AppLoggers CLI using PowerShell. Ensure you have PowerShell available.

```powershell
irm https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.ps1 | iex
```

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

### Usage Pattern 1 - App with Initial Consent Dialog

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-advanced-features/references/consent-guide.md

Example of initializing the SDK with a default strict level and updating consent based on a user dialog.

```APIDOC
## Usage Pattern 1 - App with Initial Consent Dialog

Initialize the SDK with a strict default and update consent after the user makes a choice.

```kotlin
// In Application.onCreate() - no initial consent
AppLoggerSDK.initialize(
    context = this,
    config = AppLoggerConfig.Builder()
        .defaultConsentLevel(ConsentLevel.STRICT)  // only errors until consent is obtained
        .build(),
    transport = transport
)

// When the user accepts in the consent dialog:
AppLoggerSDK.setConsent(ConsentLevel.MARKETING)

// When the user rejects:
AppLoggerSDK.setConsent(ConsentLevel.STRICT)

// When the user accepts only T&C but not marketing:
AppLoggerSDK.setConsent(ConsentLevel.PERFORMANCE)
```
```

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

### Implement Testing Utilities

Source: https://context7.com/zuccadev-labs/apploggers/llms.txt

Examples of using InMemoryLogger, FakeTransport, and other test helpers to verify logging behavior without network dependencies.

```kotlin
// InMemoryLogger para verificar que un componente loguea correctamente
val logger = InMemoryLogger()
logger.addGlobalExtra("experiment", "group_b")

myComponent.doSomething()

assertEquals(1, logger.errorCount)
logger.assertLogged(LogLevel.ERROR, tag = "PAYMENT")
logger.assertNotLogged(LogLevel.DEBUG)

// FakeTransport para verificar envíos al backend
val transport = FakeTransport(shouldSucceed = true)
// ... ejecutar operación ...
assertEquals(3, transport.sentEvents.size)

// Simular fallo de red con Retry-After
val failingTransport = FakeTransport(
    shouldSucceed = false,
    retryable = true,
    retryAfterMs = 5_000L
)

// NoOpTestLogger para tests donde el logger no es el foco
val noopLogger = NoOpTestLogger()

// FakeHealthProvider para tests de componentes que dependen del estado de salud
val healthProvider = FakeHealthProvider(HealthStatus(
    isInitialized = true,
    transportAvailable = false,
    bufferSize = 0,
    consecutiveFailures = 0
))
```

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

### Configure Multi-Project Setup

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/SUPABASE_CONFIGURATION.md

Define multiple telemetry applications by adding entries to the `projects` array. The CLI automatically detects the active project based on the workspace root.

```json
{
  "default_project": "klinema",
  "projects": [
    {
      "name": "klinema",
      "display_name": "Klinema Mobile",
      "workspace_roots": ["D:/workspace/klinema"],
      "supabase": {
        "url": "https://klinema.supabase.co",
        "api_key": "eyJhbGci..."
      }
    },
    {
      "name": "klinematv",
      "display_name": "Klinema TV",
      "workspace_roots": ["D:/workspace/klinematv"],
      "supabase": {
        "url": "https://klinematv.supabase.co",
        "api_key": "eyJhbGci..."
      }
    }
  ]
}
```

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

### Logging Best Practices in Kotlin

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/desarrollo/integration-guide.md

Examples of proper technical context logging and tag management, alongside prohibited patterns for user data and credentials.

```kotlin
// ✅ Loguear contexto técnico, no datos del usuario
AppLoggerSDK.error("STREAM", "HLS segment fetch failed",
    extra = mapOf("segment_index" to 42, "cdn_region" to "us-east-1", "retry_count" to 2))

// ✅ Usar tags consistentes en todo el módulo
object LogTags {
    const val PLAYER   = "PLAYER"
    const val NETWORK  = "NETWORK"
    const val AUTH     = "AUTH"
    const val PAYMENT  = "PAYMENT"
}

// ❌ Nunca loguear datos del usuario
AppLoggerSDK.error("AUTH", "Error for user: ${user.email}")  // Incorrecto

// ❌ Nunca loguear tokens o credenciales
AppLoggerSDK.debug("AUTH", "Token: $accessToken")  // NUNCA
```

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

### Manual Download and Install Linux/macOS

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Manually download the AppLoggers CLI binary for Linux or macOS, make it executable, and move it to a directory in your system's PATH.

```bash
# Linux / macOS
VERSION="apploggers-vX.Y.Z"
curl -L "https://github.com/zuccadev-labs/appLoggers/releases/download/${VERSION}/apploggers-linux-amd64" -o apploggers
chmod +x apploggers
sudo mv apploggers /usr/local/bin/
```

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

### Manual Download and Install Windows

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Manually download the AppLoggers CLI executable for Windows and place it in a directory that is included in your system's PATH.

```powershell
# Windows PowerShell
$version = "apploggers-vX.Y.Z"
$url = "https://github.com/zuccadev-labs/appLoggers/releases/download/$version/apploggers-windows-amd64.exe"
Invoke-WebRequest -Uri $url -OutFile "$env:ProgramFiles\apploggers.exe"
```

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

### Apploggers CLI Configuration File Example

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-cli-live-configuration/references/cli-live-setup-runbook.md

A minimal configuration for the apploggers CLI, specifying default project and Supabase credentials. Ensure sensitive keys are not versioned.

```json
{
  "default_project": "my-app",
  "projects": [
    {
      "name": "my-app",
      "display_name": "My Application",
      "workspace_roots": ["/path/to/workspace"],
      "supabase": {
        "url": "https://YOUR_PROJECT.supabase.co",
        "api_key": "eyJhbGci...",
        "schema": "apploggers"
      }
    }
  ]
}
```

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

### Compile from Source

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Compile the AppLoggers CLI from source code. This requires Git and Go (version 1.24+) to be installed. The compiled binary is then moved to a system-wide executable path.

```bash
git clone https://github.com/zuccadev-labs/appLoggers.git
cd appLoggers/cli
go build -o apploggers ./cmd/applogger-cli
sudo mv apploggers /usr/local/bin/
```

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

### Create a Test Apploggers Remote Configuration

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-cli-live-configuration/references/cli-live-setup-runbook.md

Create a test remote configuration for the apploggers CLI. This example sets a global configuration for the 'staging' environment with debug enabled.

```bash
# Crear un config de prueba (global, no device-specific)
apploggers remote-config set --environment staging --debug true --min-level debug --notes "validation test" --output json
```

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

### Install Apploggers CLI on Linux/macOS

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-cli-live-configuration/references/cli-live-setup-runbook.md

Install the apploggers CLI using a curl command to download and execute the installation script. This is for Linux and macOS systems.

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.sh | bash
```

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

### Install Specific Version Linux/macOS

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Install a specific version of the AppLoggers CLI on Linux or macOS by setting the APPLOGGERS_VERSION environment variable before running the installer script.

```bash
# Instalar una versión específica
APPLOGGERS_VERSION=apploggers-vX.Y.Z \
  curl -fsSL https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.sh | bash
```

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

### Compilar y verificar el SDK

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Ejecuta las tareas de Gradle para validar el código y generar los artefactos.

```bash
cd sdk
./gradlew check      # Lint (Detekt) + Tests unitarios
./gradlew assemble   # Compilar todos los módulos
```

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

### Install Specific Version Windows PowerShell

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Install a specific version of the AppLoggers CLI on Windows by setting the APPLOGGERS_VERSION environment variable before executing the PowerShell installation script.

```powershell
# Instalar una versión específica
$env:APPLOGGERS_VERSION = 'apploggers-vX.Y.Z'
irm https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.ps1 | iex
```

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

### Initialize and Run AppLogger CLI

Source: https://github.com/zuccadev-labs/apploggers/blob/main/cli/README.md

Build and execute the CLI from source with metadata synchronization and JSON output.

```bash
cd cli
go mod tidy
go run ./cmd/applogger-cli --syncbin-metadata --output json
```

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

### Initialize AppLogger SDK with Configuration

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-advanced-features/SKILL.md

Initialize the SDK with endpoint, API key, environment, and daily data limits. The data limit is effectively doubled on WiFi by default.

```kotlin
AppLoggerSDK.initialize(
    context = this,
    config = AppLoggerConfig.Builder()
        .endpoint(BuildConfig.LOGGER_URL)
        .apiKey(BuildConfig.LOGGER_KEY)
        .environment("production")
        .dailyDataLimitMb(50)          // 50 MB por día en datos móviles
        // En WiFi: límite efectivo = 50 × 2 = 100 MB (wifiMultiplier = 2 por defecto)
        .build(),
    transport = transport
)
```

```kotlin
val config = AppLoggerConfig.Builder()
    .endpoint(url)
    .apiKey(anonKey)
    .environment("production")
    .dailyDataLimitMb(50)
    .build()
AppLoggerIos.shared.initialize(config = config, transport = transport)
```

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

### AppLoggers CLI Installation

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Instructions for installing the AppLoggers Command Line Interface on Linux, macOS, and Windows.

```APIDOC
## AppLoggers CLI Installation

### Description
Install the AppLoggers Command Line Interface for telemetry management and operations.

### Installation Commands

#### Linux / macOS
```bash
curl -fsSL https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.sh | bash
```

#### Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/zuccadev-labs/appLoggers/main/cli/install/install.ps1 | iex
```

### Verification

```bash
apploggers version --output json
```
```

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

### Initialize and Use AppLoggers on iOS

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Demonstrates SDK initialization, logging, session management, and remote configuration for Kotlin iosMain.

```kotlin
// Debug mode: leer APPLOGGER_DEBUG de Info.plist automáticamente (sin cambiar código)
AppLoggerIos.shared.initialize(config = config, transport = transport)

// Logging básico
AppLoggerIos.shared.error("PLAYER", "Playback failed", throwable = null)
AppLoggerIos.shared.metric("buffer_time", 420.0, "ms")

// Sesión e identidad
AppLoggerIos.shared.newSession()
AppLoggerIos.shared.addGlobalExtra("experiment", "group_b")

// Device fingerprint (SHA-256 de IDFV:bundleId — automático al inicializar)
val fingerprint = AppLoggerIos.shared.getDeviceFingerprint()

// Distributed tracing — correlacionar eventos cross-device
AppLoggerIos.shared.setTraceId("order-abc-123")

// Breadcrumbs — trail de navegación
AppLoggerIos.shared.recordBreadcrumb("HomeScreen")
AppLoggerIos.shared.recordBreadcrumb("PlayerScreen")

// Beta tester
AppLoggerIos.shared.setBetaTester("tester@company.com")

// Consent (persiste en NSUserDefaults)
AppLoggerIos.shared.setConsent(true)

// Session variant para A/B testing
AppLoggerIos.shared.setVariant("checkout_v2")

// Scoped logger con tag fijo
val playerLog = AppLoggerIos.shared.scopedLogger("PLAYER")
playerLog.info("Playback started")
playerLog.error("Playback failed", throwable = null)

// Remote config — polling automático al inicializar
AppLoggerIos.shared.startRemoteConfig(intervalSeconds = 300)
AppLoggerIos.shared.stopRemoteConfig()

// Flush manual al entrar en background
AppLoggerIos.shared.flush()
```

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

### Actualización del binario

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/README.md

Comandos para actualizar la versión de la herramienta.

```bash
apploggers upgrade
apploggers upgrade --version apploggers-vX.Y.Z   # versión específica
apploggers upgrade --force                         # forzar reinstalación
```

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

### Recommended Baseline Configuration

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-production-hardening/references/runtime-tuning.md

Sets up the AppLogger with essential parameters for a production environment. Ensure to always tag the environment and disable debug mode in production.

```kotlin
AppLoggerConfig.Builder()
    .endpoint("https://tu-proyecto.supabase.co")
    .apiKey("eyJ...")
    .environment("production")                          // siempre etiquetar el entorno
    .debugMode(false)                                   // nunca true en producción
    .minLevel(LogMinLevel.INFO)                         // descarta DEBUG antes del pipeline
    .batchSize(20)                                      // 1–100 (default 20)
    .flushIntervalSeconds(30)                           // 5–300 (default 30)
    .maxStackTraceLines(50)                             // 1–100 (default 50)
    .bufferSizeStrategy(BufferSizeStrategy.FIXED)       // capacidad fija de 1000 eventos
    .bufferOverflowPolicy(BufferOverflowPolicy.DISCARD_OLDEST)
    .offlinePersistenceMode(OfflinePersistenceMode.NONE)
    .build()
```

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

### Configurar Entorno de Desarrollo de AppLogger

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/CONTRIBUTING.md

Pasos rápidos para clonar el repositorio, configurar hooks de git, y verificar la compilación del proyecto. Requiere claves de Supabase y la ruta al SDK de Android.

```bash
git clone https://github.com/zuccadev-labs/appLoggers.git && cd appLoggers

git config core.hooksPath .githooks

cp local.properties.example local.properties
# → Editar local.properties con sdk.dir y keys de Supabase

cd sdk && ./gradlew detekt :logger-core:jvmTest :logger-test:jvmTest
```

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

### iOS SDK Initialization and Usage in Swift

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs-investigation/investigation.md

Demonstrates how to initialize the AppLogger SDK in an iOS application using Swift Package Manager and how to use its public API for logging errors and metrics.

```swift
// iOS (Swift) — API pública expuesta automáticamente desde Kotlin
import AppLogger

@main
struct MyApp: App {
    init() {
        AppLoggerSDK.shared.initialize(
            config: AppLoggerConfigBuilder()
                .endpoint(endpoint: "https://tu-proyecto.supabase.co")
                .apiKey(key: "eyJ...")
                .debugMode(debug: false)
                .build()
        )
    }
}

// Uso desde Swift
AppLoggerSDK.shared.error(tag: "PLAYER", message: "Playback failed")
AppLoggerSDK.shared.metric(name: "buffer_time", value: 450.0, unit: "ms")
```

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

### Install AppLoggers macOS

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Install the AppLoggers CLI on macOS by downloading the appropriate binary for your architecture, making it executable, and moving it to the system's binary directory.

```bash
# Detectar arquitectura automáticamente
ARCH=$(uname -m | sed 's/x86_64/amd64/')
VERSION="apploggers-vX.Y.Z"

curl -L \
  "https://github.com/zuccadev-labs/appLoggers/releases/download/${VERSION}/apploggers-darwin-${ARCH}" \
  -o apploggers

chmod +x apploggers
sudo mv apploggers /usr/local/bin/
apploggers version --output json
```

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

### Consulta de versión

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/README.md

Obtención de la versión actual de la CLI.

```bash
apploggers version
apploggers version --output json
```

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

### AppLogger Agent: Telemetry Query Example

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Example of an AI agent instruction to query error logs and summarize by severity. This command is optimized for machine readability.

```bash
apploggers telemetry agent-response \
  --source logs \
  --severity error \
  --aggregate severity \
  --from <timestamp-inicio-ISO8601> \
  --to <timestamp-fin-ISO8601> \
  --preview-limit 3 \
  --output agent
```

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

### Configuración de cli.json

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/SUPABASE_CONFIGURATION.md

Archivo de configuración local para el CLI de AppLoggers. Debe mantenerse fuera del control de versiones debido a que contiene la service_role key.

```json
{
  "default_project": "my-app",
  "projects": [
    {
      "name": "my-app",
      "display_name": "My Application",
      "workspace_roots": ["D:/workspace/my-app"],
      "supabase": {
        "url": "https://xxxx.supabase.co",
        "api_key": "eyJhbGci...",
        "schema": "apploggers"
      }
    }
  ]
}
```

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

### Verify Apploggers Installation and Connectivity

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/INSTALLATION.md

Commands to verify the Apploggers CLI installation and its connection to Supabase. Includes checking the version, health status, and performing a sample telemetry query.

```bash
# Verificar instalación
apploggers version --output json

# Verificar conectividad con Supabase
apploggers health --output json

# Primer query
apploggers telemetry query \
  --source logs \
  --aggregate severity \
  --limit 10 \
  --output json
```

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

### AppLogger: Privacy Policy Disclosure Example

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs-investigation/privacy-compliance.md

Provides an example text for an app's privacy policy to disclose the collection of technical telemetry data. This text should be adapted to fit the specific app's practices.

```plaintext
Recopilación de datos técnicos:
La aplicación recopila automáticamente datos técnicos anónimos sobre el funcionamiento 
del software (registros de errores, versión del sistema operativo, modelo del dispositivo) 
con el fin de mejorar la estabilidad de la aplicación. Estos datos no incluyen información 
personal identificable y se eliminan automáticamente transcurridos 30 días.
```

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

### Iniciar un rastreo con startTrace

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-advanced-features/references/operation-trace-guide.md

Ejemplos de inicialización de un span, con o sin atributos iniciales.

```kotlin
// Sin atributos iniciales
val trace = AppLoggerSDK.startTrace("screen_load")

// Con atributos iniciales (vararg de Pair<String, Any>)
val trace = AppLoggerSDK.startTrace("video_load",
    "content_id" to contentId,
    "quality" to "4K"
)
```

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

### Daily Development Workflow Steps

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Follow these steps for the normal development flow: create a branch from 'dev', make commits using Conventional Commits, push to origin, and open a Pull Request. Ensure CI checks pass before merging.

```bash
git checkout dev && git pull
git checkout -b feat/nombre-de-la-feature
```

```bash
git commit -m "feat(core): descripción clara"
# → commit-msg hook: valida Conventional Commits
```

```bash
git push origin feat/nombre-de-la-feature
# → pre-push hook: corre Detekt + jvmTest
# → Si fallan: corregir y volver al paso 2
```

```bash
gh pr create --base dev --title "feat(core): ..." --body "..."
# → CI remoto: lint → test → security
```

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

### Verify act Version

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Checks the installed version of the 'act' tool.

```bash
act --version
# act version 0.2.x
```

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

### Verify Java Version

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Checks if Java 17 is installed and configured correctly.

```bash
java -version
# openjdk version "17.0.x" 2024-xx-xx
# OpenJDK Runtime Environment Temurin-17.0.x
```

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

### Crear local.properties desde el template

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Copia el archivo de ejemplo para inicializar la configuración local.

```bash
cp local.properties.example local.properties
```

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

### AppLoggers CLI - Telemetry Query

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Examples of querying telemetry data using the AppLoggers CLI.

```APIDOC
## AppLoggers CLI - Telemetry Query

### Description
Query and retrieve telemetry data, such as logs, with various filters.

### Query Logs

Query the last 50 error logs from the past 24 hours.

```bash
apploggers telemetry query \
  --source logs \
  --severity error \
  --limit 50 \
  --output json
```

### Agent Response Format

Get a compact response for agents, aggregating by severity.

```bash
apploggers telemetry agent-response \
  --source logs \
  --aggregate severity \
  --preview-limit 3 \
  --output agent
```

### Filter by Device Fingerprint

Query logs associated with a specific device fingerprint.

```bash
apploggers telemetry query \
  --source logs \
  --fingerprint "sha256..." \
  --output json
```
```

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

### Operation Trace Output Formats

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-instrumentation-design/references/event-taxonomy.md

Examples of metrics and error events emitted by the trace system.

```text
name:  "trace.checkout_flow"
value: 1250.0                    // duration_ms
unit:  "ms"
tags:  {
  duration_ms: 1250,
  trace_id: "uuid",
  success: true,
  payment_method: "card",        // atributo inicial
  amount_cents: 9900,            // añadido con tag()
  order_id: "order-xyz"          // extraAttributes en end()
}
```

```text
tag:     "Trace.checkout_flow"
message: "trace.checkout_flow failed after 3001ms"
extra:   { duration_ms: 3001, trace_id: "uuid", success: false,
           failure_reason: "card_declined", payment_method: "card" }
```

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

### Configure JAVA_HOME in gradle.properties

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Update the Gradle Java home path to match the local JDK installation.

```properties
# sdk/gradle.properties
org.gradle.java.home=C:\\Program Files\\Eclipse Adoptium\\jdk-17.0.x.x-hotspot
```

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

### Instalar dependencias vía JitPack

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Agrega el repositorio de JitPack y las dependencias necesarias al proyecto.

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

// app/build.gradle.kts
dependencies {
    // Core del logger (obligatorio)
    // Reemplazar <latest-version> con la última release: https://github.com/zuccadev-labs/appLoggers/releases
    implementation("com.github.zuccadev-labs.appLoggers:logger-core:<latest-version>")

    // Transporte Supabase (opcional — si tu backend es Supabase)
    implementation("com.github.zuccadev-labs.appLoggers:logger-transport-supabase:<latest-version>")

    // Utilidades de testing (solo para tests)
    testImplementation("com.github.zuccadev-labs.appLoggers:logger-test:<latest-version>")
}
```

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

### Configurar variables en local.properties

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Define las rutas del SDK y las credenciales de Supabase. Este archivo debe permanecer fuera del control de versiones.

```properties
# ── Android SDK ──────────────────────────────────────────────────────────
# Android Studio lo configura automáticamente.
# Solo modificar si tu SDK está en una ruta custom.
sdk.dir=C:\\Users\\TU_USUARIO\\AppData\\Local\\Android\\Sdk

# ── Supabase (backend de logs) ──────────────────────────────────────────
# Obtener desde el proyecto Supabase con `Connect` o `API Keys`
APPLOGGER_URL=https://TU-PROYECTO.supabase.co
APPLOGGER_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# ── Modo Debug ──────────────────────────────────────────────────────────
# true  → logs en Logcat + envío al backend (desarrollo)
# false → solo envío al backend, sin output local (producción)
APPLOGGER_DEBUG=true
```

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

### Deduplication Behavior Example

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-guided-setup/references/config-reference.md

Conceptual representation of how the SDK handles repeated errors within the deduplication window.

```kotlin
// Si el mismo error ocurre 50 veces en 10 segundos:
// → Solo se envía 1 evento con occurrence_count = 50
// → En lugar de 50 filas en Supabase
```

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

### Configuración multi-proyecto en cli.json

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/cli/README.md

Ejemplo de configuración para múltiples proyectos con autodetección basada en rutas de trabajo.

```json
{
  "default_project": "klinema",
  "projects": [
    {
      "name": "klinema",
      "display_name": "Klinema Mobile",
      "workspace_roots": ["D:/workspace/klinema-app"],
      "supabase": {
        "url": "https://klinema.supabase.co",
        "api_key": "eyJhbGci..."
      }
    },
    {
      "name": "klinematv",
      "display_name": "Klinema TV",
      "workspace_roots": ["D:/workspace/klinematv"],
      "supabase": {
        "url": "https://klinematv.supabase.co",
        "api_key": "eyJhbGci..."
      }
    }
  ]
}
```

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

### Verify Docker Version

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Checks if Docker is installed and running, ensuring the server version meets the minimum requirement.

```bash
docker version
# Requiere: Server Version: 24.x o superior
```

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

### Initialize act secrets

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/dev-environment.md

Prepare the local secrets file for use with act.

```bash
cp .act.secrets.example .act.secrets
# Completar los valores en .act.secrets
```

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

### Testing Utilities Usage

Source: https://github.com/zuccadev-labs/apploggers/blob/main/README.md

Examples of using the logger-test module to verify logging behavior and simulate transport states.

```kotlin
// Verificar que un componente loguea correctamente
val logger = InMemoryLogger()
logger.addGlobalExtra("experiment", "group_b")  // global extra funcional
myComponent.doSomething()
assertEquals(1, logger.errorCount)
logger.assertLogged(LogLevel.ERROR, tag = "PAYMENT")
logger.assertNotLogged(LogLevel.DEBUG)

// FakeTransport para verificar envíos al backend
val transport = FakeTransport(shouldSucceed = true)
assertEquals(3, transport.sentEvents.size)

// Simular fallo de red con Retry-After
val failingTransport = FakeTransport(shouldSucceed = false, retryable = true, retryAfterMs = 5_000L)

// NoOpTestLogger para tests donde el logger no es el foco
val logger = NoOpTestLogger()

// FakeHealthProvider para tests de componentes que dependen del estado de salud
val provider = FakeHealthProvider(HealthStatus(isInitialized = true, transportAvailable = false, ...))
```

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

### Definición del punto de entrada startTrace

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-advanced-features/references/operation-trace-guide.md

Firma de la función de extensión utilizada para iniciar un nuevo span de rastreo.

```kotlin
fun AppLogger.startTrace(operation: String, vararg attributes: Pair<String, Any>): OperationTrace
```

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

### Android TV Device Info JSON Structure

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs-investigation/db-migration.md

Example of the `device_info` JSONB field for an Android TV device.

```json
{
  "brand": "Philips",
  "model": "PFL6008",
  "os_version": "11",
  "api_level": 30,
  "platform": "android_tv",
  "app_version": "2.1.0",
  "app_build": 210,
  "is_low_ram": true,
  "is_tv": true,
  "connection_type": "ethernet"
}
```

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

### Android Mobile Device Info JSON Structure

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs-investigation/db-migration.md

Example of the `device_info` JSONB field for an Android mobile device.

```json
{
  "brand": "Google",
  "model": "Pixel 7",
  "os_version": "14",
  "api_level": 34,
  "platform": "android_mobile",
  "app_version": "2.1.0",
  "app_build": 210,
  "is_low_ram": false,
  "is_tv": false,
  "connection_type": "wifi"
}
```

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

### Comandos de publicación Gradle

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/paquete/publishing.md

Comandos para publicar artefactos KMP en repositorios Maven.

```bash
# Publicar todo (metadata + targets) a un repo Maven
./gradlew publishAllPublicationsToGitHubPackagesRepository

# Publicar solo Android release
./gradlew publishAndroidReleasePublicationToGitHubPackagesRepository

# Publicar solo metadata KMP
./gradlew publishKotlinMultiplatformPublicationToGitHubPackagesRepository
```

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

### Log Critical Business Failures

Source: https://github.com/zuccadev-labs/apploggers/blob/main/docs/ES/agents/applogger-instrumentation-design/references/event-taxonomy.md

Examples for logging high-impact failures such as payment transactions or media playback errors.

```kotlin
// Fallo de pago
AppLoggerSDK.error("PAYMENT", "Transaction failed", throwable = e, extra = mapOf(
    "error_code" to "INSUFFICIENT_FUNDS",
    "amount_cents" to 9900
))

// Fallo de reproducción
AppLoggerSDK.error("PLAYER", "Playback failed", throwable = e, extra = mapOf(
    "content_id" to "movie_123",
    "codec" to "h264",
    "segment_index" to 42
))
```