or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-ktor--ktor-client-logging-macosx64

Ktor HTTP client logging plugin for macOS x64 platform with configurable log levels and output formats

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-logging-macosx64@3.2.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-logging-macosx64@3.2.0

index.mddocs/

Ktor Client Logging

Ktor Client Logging is a plugin for the Ktor HTTP client that provides comprehensive logging capabilities for HTTP requests and responses. It offers configurable log levels, multiple output formats, header sanitization for security, and custom logger implementations with full coroutine safety.

Package Information

  • Package Name: io.ktor:ktor-client-logging-macosx64
  • Package Type: maven
  • Language: Kotlin (Multiplatform - macOS x64)
  • Target Platform: macOS x64 (Native compilation target)
  • Installation: 
    implementation("io.ktor:ktor-client-logging:3.2.0")

Core Imports

import io.ktor.client.plugins.logging.*
import io.ktor.client.*
import io.ktor.client.request.*  // For HttpRequestBuilder (used in filters)
import io.ktor.http.*            // For HttpMethod, ContentType (used in examples)

Basic Usage

import io.ktor.client.*
import io.ktor.client.plugins.logging.*
import io.ktor.client.request.*

// Basic logging setup
val client = HttpClient {
    install(Logging) {
        level = LogLevel.ALL
        logger = Logger.SIMPLE
    }
}

// Make a request - will be automatically logged
val response = client.get("https://api.example.com/users")
client.close()

Architecture

The Ktor Client Logging plugin integrates seamlessly with Ktor's client plugin architecture:

  • Plugin Installation: Uses Ktor's standard install() mechanism with configuration DSL
  • Hook System: Intercepts HTTP pipeline phases (Send, Receive, Response) for comprehensive logging
  • Logger Abstraction: Platform-agnostic Logger interface with concrete implementations
  • Coroutine Safety: Thread-safe logging operations compatible with Ktor's coroutine-based architecture
  • Content Handling: Intelligent binary/text detection and streaming response support

Capabilities

Plugin Installation and Configuration

Install and configure the logging plugin in your HTTP client.

fun HttpClientConfig<*>.Logging(block: LoggingConfig.() -> Unit = {})

val Logging: ClientPlugin<LoggingConfig>

Usage Example:

val client = HttpClient {
    install(Logging) {
        level = LogLevel.HEADERS
        logger = Logger.DEFAULT
        format = LoggingFormat.Default
        
        // Filter specific requests
        filter { request ->
            request.url.host == "api.example.com"
        }
        
        // Sanitize sensitive headers
        sanitizeHeader { header ->
            header == "Authorization"
        }
    }
}

Logging Configuration

Configure logging behavior through the LoggingConfig class.

@KtorDsl
class LoggingConfig {
    var format: LoggingFormat
    var logger: Logger
    var level: LogLevel
    
    fun filter(predicate: (HttpRequestBuilder) -> Boolean)
    fun sanitizeHeader(placeholder: String = "***", predicate: (String) -> Boolean)
}

Logging Levels

Control the amount of information logged with different log levels.

enum class LogLevel(
    val info: Boolean,
    val headers: Boolean,
    val body: Boolean
) {
    ALL(true, true, true),
    HEADERS(true, true, false),
    BODY(true, false, true),
    INFO(true, false, false),
    NONE(false, false, false)
}

Usage Example:

install(Logging) {
    level = LogLevel.ALL  // Log everything
    // level = LogLevel.HEADERS  // Log info and headers only
    // level = LogLevel.INFO  // Log basic info only
    // level = LogLevel.NONE  // Disable logging
}

Logging Formats

Choose between different output formats for logged information.

enum class LoggingFormat {
    Default,
    OkHttp
}

Usage Example:

install(Logging) {
    format = LoggingFormat.Default  // Standard Ktor format
    // format = LoggingFormat.OkHttp  // OkHttp-compatible format
}

Logger Interface

Implement custom logging behavior through the Logger interface.

interface Logger {
    fun log(message: String)
    
    companion object
}

Built-in Loggers

Platform-specific logger implementations for different environments.

// Common loggers available on all platforms
val Logger.Companion.SIMPLE: Logger
val Logger.Companion.EMPTY: Logger

// Platform-specific default logger
expect val Logger.Companion.DEFAULT: Logger

For macOS (Native/POSIX platforms):

actual val Logger.Companion.DEFAULT: Logger  // Uses SIMPLE logger

Note: Logger.DEFAULT uses Kotlin Multiplatform's expect/actual mechanism to provide platform-specific implementations. On macOS x64 (and other POSIX platforms), it delegates to Logger.SIMPLE which outputs to standard output. This is different from JVM platforms which may use more sophisticated logging frameworks.

Usage Examples:

install(Logging) {
    logger = Logger.SIMPLE    // Prints to stdout with "HttpClient:" prefix
    // logger = Logger.DEFAULT  // Platform-specific logger
    // logger = Logger.EMPTY    // No-op logger for testing
    
    // Custom logger
    logger = object : Logger {
        override fun log(message: String) {
            println("Custom: $message")
        }
    }
}

Request Filtering

Filter which requests should be logged based on custom criteria.

fun LoggingConfig.filter(predicate: (HttpRequestBuilder) -> Boolean)

Usage Example:

install(Logging) {
    // Only log requests to specific domains
    filter { request ->
        request.url.host.contains("api.example.com")
    }
    
    // Only log POST requests
    filter { request ->
        request.method == HttpMethod.Post
    }
    
    // Multiple filters (all must pass)
    filter { request -> request.url.protocol.isSecure() }
    filter { request -> !request.url.pathSegments.contains("health") }
}

Header Sanitization

Sanitize sensitive header values to prevent exposure in logs.

fun LoggingConfig.sanitizeHeader(
    placeholder: String = "***", 
    predicate: (String) -> Boolean
)

Note: When using LoggingFormat.OkHttp, the plugin internally uses "██" as the default placeholder regardless of the configured placeholder value.

Usage Example:

install(Logging) {
    // Sanitize Authorization headers
    sanitizeHeader { header -> 
        header.equals("Authorization", ignoreCase = true)
    }
    
    // Sanitize multiple headers with custom placeholder
    sanitizeHeader("████") { header ->
        header in listOf("Authorization", "X-API-Key", "Cookie")
    }
    
    // Sanitize based on header patterns
    sanitizeHeader { header ->
        header.contains("token", ignoreCase = true) ||
        header.contains("secret", ignoreCase = true)
    }
}

Error Handling

The logging plugin is designed to be resilient and will not throw exceptions that interrupt HTTP requests:

  • Binary Content Detection: Automatically detects and handles binary content to avoid logging corruption
  • Content Length Handling: Gracefully handles unknown content lengths and streaming responses
  • Encoding Support: Properly handles different character encodings and compressed content
  • Exception Isolation: Logging failures are caught and handled without affecting HTTP operations

Common Patterns:

install(Logging) {
    level = LogLevel.ALL
    
    // The plugin will automatically:
    // - Detect binary vs text content
    // - Handle streaming responses
    // - Sanitize specified headers
    // - Log request/response exceptions
    // - Preserve original request/response data
}