http logging

http logging captures request and response data flowing through port forwards, enabling debugging of API interactions, performance analysis, and security auditing. this feature helps developers understand what their applications are actually sending and receiving.

when http logging helps

http logging becomes valuable when debugging API integration issues, investigating performance problems, or understanding communication patterns between services. this comes up especially when local development connects to remote services and something isn't working as expected.

without traffic visibility, developers often resort to adding debug statements to application code or using separate network monitoring tools. http logging provides integrated traffic capture directly in the port-forwarding tool.

this feature currently works only in the desktop interface, not the terminal version.

how traffic capture works

kftray sits between local applications and forwarded services, allowing it to intercept and log http traffic transparently. when http logging is enabled for a configuration, the tool captures both request and response data, including headers, body content, and timing information.

the capture happens at the network level, so it works regardless of the application or framework being used. any http traffic flowing through the port forward gets logged automatically.

enabling and configuring logging

enable http logging for specific port forward configurations through the configuration menu. each configuration can have logging enabled or disabled independently, allowing selective monitoring of only the services that need debugging.

logs are saved to ~/.kftray/http_logs/ with filenames based on configuration ID and local port, making it easy to find logs for specific services.

the logging process creates separate files for each configuration, preventing logs from different services from mixing together in a single file.

log format and structure

each http transaction creates log entries that correlate requests with their responses using trace IDs:

----------------------------------------
Trace ID: 5525d312-5582-46ad-85d1-0fd3710f824e
Request at: 2024-06-13T15:34:09.756706+00:00
Method: GET
Path: /api/users
Version: 1

Headers:
Host: localhost:8080
Connection: keep-alive
Accept: application/json

Body:
<empty>

----------------------------------------
Trace ID: 5525d312-5582-46ad-85d1-0fd3710f824e
Response at: 2024-06-13T15:34:09.901304+00:00
Took: 144 ms
Status: 200

Headers:
Content-Type: application/json
Content-Length: 42

Body:
{
  "users": [
    {"id": 1, "name": "John"}
  ]
}

the trace ID links requests to their corresponding responses, making it easy to track complete API interactions. timing information shows response latency, and full headers and body content provide complete transaction details.

realistic debugging scenarios

api integration problems

when a local application fails to communicate properly with a cluster service, http logging reveals the actual requests being sent and responses received:

# Request shows what the application is actually sending
Method: POST
Path: /api/auth/login
Body: {"username": "test", "password": "wrong"}

# Response shows the actual error
Status: 401
Body: {"error": "Invalid credentials", "code": "AUTH_FAILED"}

this helps distinguish between application bugs, configuration issues, and service problems.

performance investigation

slow API responses become visible through timing information in the logs:

# Fast endpoint
Request at: 15:34:09.756706
Response at: 15:34:09.801304
Took: 45 ms

# Slow endpoint  
Request at: 15:35:12.123456
Response at: 15:35:15.987654
Took: 3864 ms

patterns in response times help identify performance bottlenecks and guide optimization efforts.

security and authentication debugging

authentication header problems become apparent in captured traffic:

# Missing authorization header
Headers:
Host: localhost:8080
Content-Type: application/json

# Response indicates auth failure
Status: 403
Body: {"error": "Authorization header required"}

this helps debug oauth flows, API key configurations, and other authentication mechanisms.

log management and maintenance

viewing captured traffic

access logs through the configuration menu in the desktop interface. logs open in the system's default text editor, making them easy to search and analyze.

each configuration maintains its own log file, so traffic from different services stays separated for easier debugging.

cleaning up log files

http logs can grow large over time, especially for high-traffic services. regular cleanup prevents disk space issues and keeps logs manageable.

the application provides a bulk log cleanup option through the main menu, or individual log files can be deleted manually from the filesystem.

disk usage considerations

high-traffic applications generate large log files quickly. monitor disk usage when logging busy APIs, and consider selective logging (enabling only for specific debugging sessions) rather than continuous logging.

binary content (images, files) in request/response bodies contributes significantly to log file size.

use case patterns

microservices communication debugging

when debugging communication between microservices, enable logging on the services involved in the interaction chain. this reveals the complete communication flow and helps identify where problems occur.

for example, logging both the API gateway and backend service shows how requests transform as they flow through the system.

third-party api integration

when integrating with external APIs through cluster services, http logging shows exactly what requests are being made and what responses are received, helping debug integration issues.

this particularly helps when API documentation doesn't match actual service behavior.

load balancing and routing verification

in environments with complex routing (service meshes, ingress controllers), http logging verifies that requests reach the intended services and responses return correctly.

headers often contain routing information that helps understand load balancing behavior.

security and privacy considerations

sensitive data in logs

http logs capture complete request and response content, including potentially sensitive data like passwords, API keys, and personal information. review what data flows through logged services and handle log files appropriately.

consider selective logging that excludes sensitive endpoints or configure log rotation to limit data retention.

log file security

log files are stored locally and are readable by the user running kftray. on shared systems, consider file permissions and storage location for logs containing sensitive data.

team sharing of log files should follow the same security practices as the underlying service data.

regulatory compliance

in regulated environments, http logging may need to comply with data retention and privacy requirements. consider these requirements when enabling logging for production services or services handling regulated data.

performance impact and limitations

overhead considerations

http logging adds minimal latency to individual requests but consumes additional memory and disk space. the impact increases with request/response size and traffic volume.

for very high-throughput services, consider the performance impact of logging and use it selectively for debugging rather than continuous monitoring.

logging limitations

http logging only captures http traffic -- other protocols (database connections, message queues) aren't logged. binary protocols and non-http traffic pass through without capture.

encrypted traffic (https) is logged after decryption at the port forward level, showing the plaintext content that applications send and receive.

troubleshooting logging issues

no logs appearing

when logging is enabled but no logs appear, verify that traffic is actually flowing through the port forward and that the traffic is http. database connections and other protocols won't generate http logs.

check that the port forward is active and applications are connecting through the forwarded port rather than directly to cluster services.

incomplete log entries

missing request or response data often indicates connection problems or non-http traffic. verify that applications are making complete http requests and receiving responses.

binary content may not display properly in text-based log files but still appears in the logs.

log file permission problems

if logs can't be written, check file system permissions for the ~/.kftray/http_logs/ directory and available disk space.

the application needs write access to the log directory and sufficient disk space for log file growth.