Network Instrumentation

Generates: Spans

Automatically instruments HTTP requests made via OkHttp and HttpURLConnection.

How It Works

Pulse Android SDK automatically instruments HTTP requests when using:

• OkHttp 3.0+ - Most popular HTTP client library for Android
• HttpURLConnection - Standard Java HTTP client
• HttpsURLConnection - Secure HTTP connections

The instrumentation operates by intercepting application calls to these APIs, creating client HTTP spans with request/response metadata.

Quick Start

Add these dependencies to your project

Replace BYTEBUDDY_VERSION with the latest release.

Byte buddy compilation plugin

This plugin leverages Android's Transform API to instrument bytecode at compile time. You can find more info on its repo page.

Root Project dependencies

plugins {
    id("net.bytebuddy.byte-buddy-gradle-plugin") version "BYTEBUDDY_VERSION"
}

Project dependencies

// if you are using OkHttp then use below libraries
implementation("in.horizonos.instrumentation:okhttp3-library:0.0.1-alpha")
byteBuddy("in.horizonos.instrumentation:okhttp3-agent:0.0.1-alpha")

// for httpurlconnection
implementation("in.horizonos.instrumentation:httpurlconnection-library:0.0.1-alpha")
byteBuddy("in.horizonos.instrumentation:httpurlconnection-agent:0.0.1-alpha")

After adding the plugin and the dependencies to your project, your OkHttp requests will be traced automatically.

Configuration

Network instrumentation is enabled by default when using the Android agent. You can configure it during SDK initialization:

PulseSDK.INSTANCE.initialize(
    application = this,
    endpointBaseUrl = "https://your-backend.com",
) {
    network {
        enabled(true)  // Enabled by default
    }
}

What Gets Tracked

All HTTP requests are automatically captured, including:

• OkHttp requests (OkHttp 3.0+)
• HttpURLConnection requests
• HttpsURLConnection requests

Each network request automatically captures HTTP method, URL, status code, protocol version, server information, headers, and error details. See the Attributes section below for complete details.

Generated Telemetry

Type: Span
Span Name: HTTP {method} (e.g., HTTP GET, HTTP POST)
Span Kind: CLIENT
pulse.type: network

Attributes

Network-Specific Attributes

Attribute	Description	Example	Always Present
pulse.type	Instrumentation type	"network"	✅ Yes
http.method	HTTP method	"GET", "POST"	✅ Yes
http.url	Full request URL	"https://api.example.com/users/123"	✅ Yes
http.scheme	URL scheme	"https"	⚠️ Only if URL is parseable
http.host	Request hostname	"api.example.com"	⚠️ Only if URL is parseable
http.target	Request path	"/users/123"	⚠️ Only if URL is parseable
http.flavor	Protocol version	"1.1", "2.0"	⚠️ Only if available
http.status_code	Response status code	200, 404, 500	⚠️ Only if response received
net.peer.name	Server hostname	"api.example.com"	⚠️ Only if URL is parseable
net.peer.port	Port number	443, 8080	⚠️ Only if URL contains port

Error Attributes (on failure)

Attribute	Description	Example
error	Error flag	true
exception.type	Exception class name	"java.net.SocketTimeoutException"
exception.message	Exception message	"Connection timed out"

Note: The SDK automatically records exceptions on spans when network requests fail, following OpenTelemetry semantic conventions.

Sample Payload: Successful Network Request

{
  "name": "HTTP GET",
  "kind": "CLIENT",
  "startTimeUnixNano": "1701000020000000000",
  "endTimeUnixNano": "1701000020317250000",
  "duration": "317.25ms",
  "attributes": {
    "pulse.type": "network",
    "http.method": "GET",
    "http.url": "https://api.example.com/users/123",
    "http.scheme": "https",
    "http.host": "api.example.com",
    "http.target": "/users/123",
    "http.status_code": 200,
    "http.flavor": "1.1",
    "net.peer.name": "api.example.com",
    "net.peer.port": 443
  }
}

Sample Payload: Failed Network Request

{
  "name": "HTTP POST",
  "kind": "CLIENT",
  "status": "ERROR",
  "startTimeUnixNano": "1701000030000000000",
  "endTimeUnixNano": "1701000030500000000",
  "duration": "50ms",
  "attributes": {
    "pulse.type": "network",
    "http.method": "POST",
    "http.url": "https://api.example.com/orders",
    "http.scheme": "https",
    "http.host": "api.example.com",
    "http.target": "/orders",
    "http.status_code": 0,
    "net.peer.name": "api.example.com",
    "error": true,
    "exception.type": "java.net.SocketTimeoutException",
    "exception.message": "Connection timed out"
  }
}

Global Attributes

All network spans include global attributes (service, device, OS, session, network carrier, etc.). See Global Attributes for complete list.

Disabling Network Instrumentation

When network { enabled(false) }, network requests are not automatically tracked. No spans are created for HTTP requests.

Note: You can still manually instrument network requests using Custom Spans.