calltelemetry/traceroute repository overview

⁠Traceroute Service

A high-performance, distributed traceroute service built with Elixir/OTP that provides both HTTP REST API and NATS message-based network path tracing capabilities.

⁠🚀 Features

• HTTP REST API - Simple HTTP POST endpoint for traceroute requests
• NATS Integration - Event-driven traceroute processing via NATS messaging
• Fault Tolerant - Built on Elixir/OTP supervision trees for reliability
• JSON Responses - Structured JSON output with detailed path information
• Docker Ready - Containerized deployment with health checks
• Comprehensive Testing - 89% test coverage with property-based testing
• Performance Optimized - Concurrent request handling with timeout management

⁠📋 Requirements

• Elixir: 1.18.4+
• Erlang/OTP: 26.2.5.2+
• NATS Server: For message-based processing
• Elevated Privileges: Required for ICMP traceroute operations

⁠🛠 Installation

⁠Local Development

# Clone the repository
git clone <repository-url>
cd traceroute

# Install dependencies
mix deps.get

# Set up environment
source local-test.env  # if available

# Run tests
mix test

# Start the service
mix run --no-halt

⁠Docker Deployment

# Build the image
docker build -t traceroute:latest .

# Run with CAP_NET_RAW capability for ICMP (recommended - more secure)
docker run --cap-add=NET_RAW -p 4100:4100 traceroute:latest

# Alternative: Run with full privileged access (less secure)
docker run --privileged -p 4100:4100 traceroute:latest

Security Note: The image now runs as a non-root user (appuser:1001) with only the CAP_NET_RAW capability required for ICMP operations. This follows security best practices while maintaining full traceroute functionality.

⁠🔧 Configuration

⁠Environment Variables

• NATS_HOST - NATS server host (default: "nats")
• NATS_PORT - NATS server port (default: 4222)
• HTTP_PORT - HTTP service port (default: 4100)
• MIX_ENV - Environment (dev/test/prod)

⁠NATS Configuration

The service connects to NATS for distributed message processing:

# Configured in lib/tracer.ex
%{
  host: System.get_env("NATS_HOST", "nats"),
  port: String.to_integer(System.get_env("NATS_PORT", "4222"))
}

⁠📡 API Usage

⁠HTTP REST API

Endpoint: POST /traceroute

Request:

curl -X POST http://localhost:4100/traceroute \
  -H "Content-Type: application/json" \
  -d '{"host": "google.com"}'

Response:

{
  "status": 200,
  "body": {
    "result": "ok",
    "message": "Traceroute successful to google.com",
    "next_hop_ip": "172.217.14.46",
    "next_hop_hostname": "lga25s78-in-f14.1e100.net",
    "next_hop_fqdn": "lga25s78-in-f14.1e100.net"
  }
}

⁠NATS Message API

Topic: traceroute.request

Message Format:

{
  "body": "google.com",
  "reply_to": "response.topic"
}

Response: JSON structure similar to HTTP API response

⁠🏗 Architecture

⁠Core Components

• Tracer - Main application supervisor
• Tracer.Worker - Traceroute execution logic
• Tracer.Web.Handler - HTTP request handler
• NATS.Listener - NATS message processor
• Tracer.Web.Supervisor - Web server supervision

⁠Data Flow

1. HTTP Request → Tracer.Web.Handler → Tracer.Worker → Response
2. NATS Message → NATS.Listener → Tracer.Worker → Reply

⁠Key Functions

⁠Tracer.Worker

• trace/1 - Main traceroute execution
• clean_timeouts/1 - Filter timeout responses
• get_last_hop/1 - Extract meaningful hop information
• process_results/2 - Format response data

⁠🧪 Testing

⁠Running Tests

# Run all tests
mix test

# Run with coverage
mix test --cover

# Run specific test files
mix test test/trace/worker_test.exs
mix test test/trace/handler_test.exs

# Run excluding privileged tests
mix test --exclude integration

⁠Test Coverage

Current coverage: 89.0%

⁠Test Structure

• Unit Tests - test/trace/worker_test.exs, test/trace/handler_test.exs
• Integration Tests - test/integration_test.exs
• NATS Tests - test/nats_listener_test.exs
• Supervisor Tests - test/trace/supervisor_test.exs
• Property-based Tests - StreamData generators (commented due to complexity)

⁠Test Dependencies

# Test-only dependencies in mix.exs
{:mox, "~> 1.1", only: :test},           # Mocking
{:stream_data, "~> 1.0", only: :test},   # Property-based testing
{:excoveralls, "~> 0.18", only: :test},  # Coverage reporting
{:ex_machina, "~> 2.8", only: :test}     # Test factories

⁠🐳 Docker

⁠Dockerfile

FROM elixir:1.18.4 AS builder
# Multi-stage build for optimized production image
# Includes libssl for cryptographic operations

⁠DevSpace Configuration

# devspace.yaml for Kubernetes development
deployments:
  - name: traceroute
    helm:
      chart:
        name: ./charts/traceroute

⁠🔍 Monitoring & Debugging

⁠Logging

The service provides structured logging:

• Info: Successful traceroute operations
• Error: Failed operations, privilege issues
• Debug: NATS connection status

⁠Health Checks

• HTTP endpoint responds to basic connectivity
• NATS connection monitoring
• Process supervision with automatic restarts

⁠🚨 Production Considerations

⁠Security

• Privileged Access: Required for ICMP operations
• Input Validation: All host inputs are validated
• Error Handling: Graceful degradation on permission errors

⁠Performance

• Concurrent Requests: Multiple traceroute operations can run simultaneously
• Timeout Handling: Configurable timeouts prevent hanging operations
• Memory Management: Automatic garbage collection and process cleanup

⁠Deployment

# Production build
MIX_ENV=prod mix release

# Docker production
docker build --build-arg BUILD_ENV=prod -t traceroute:prod .

# Kubernetes deployment
kubectl apply -f k8s/

⁠🤝 Contributing

⁠Development Setup

1. Install required versions (see .tool-versions)
2. Run mix setup to install dependencies
3. Ensure NATS server is running locally
4. Run tests to verify setup: mix test

⁠Code Quality

# Format code
mix format

# Run static analysis
mix credo

# Type checking (if configured)
mix dialyzer

# Full quality suite
mix quality

⁠Adding Tests

• Unit tests for pure functions
• Integration tests for API endpoints
• Mock external dependencies using Mox
• Use property-based testing for edge cases

⁠📚 Additional Resources

• Elixir Documentation⁠
• OTP Design Principles⁠
• NATS.io Documentation⁠
• gen_icmp Library⁠

⁠📄 License

See LICENSE file for details.

⁠🆘 Support

For issues and support:

1. Check existing tests for usage examples
2. Review logs for error details
3. Ensure proper privileges for ICMP operations
4. Verify NATS connectivity

Built with ❤️ using Elixir/OTP for reliable, concurrent network diagnostics.