Location Instrumentation

Generates: Attributes on spans and log records

Automatically adds geo attributes to spans and log records based on the device's location.

How It Works

The location instrumentation enriches all spans and log records with geo attributes when location data is available. It uses the device's location services and reverse geocoding to provide latitude, longitude, country, region, locality, and postal code information.

Location data is cached by 1 hour to minimize battery usage and avoid excessive geo coder calls. The periodic refresh is automatically paused when the app is backgrounded and resumed when foregrounded.

Installation

Add the location library module to your dependencies:

dependencies {
    implementation("org.dreamhorizon.instrumentation:location-location-library:<latest-version>")
}

Replace <latest-version> with the latest release. You can find available versions on Central Sonatype.

Once you initialize the SDK, the location instrumentation starts automatically. No additional configuration is required.

Permissions

Your app must have location permission granted. Add the appropriate permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Without permissions or location data

If location permission is not granted or location is not available, no geo attributes will be added to spans or log records.

Behavior

• Caching: Location data is cached to avoid multiple geo coder calls and location fetches. The cache expires after 1 hour.
• Refresh cycle:
  • On app start, the instrumentation checks if the cache is valid. If expired or missing, it fetches location immediately. Otherwise, it uses cached data.
  • After the initial check, location is refreshed every cache invalidation period.
• Battery optimization: Periodic refresh is automatically paused when the app is backgrounded and resumed when foregrounded.
• Cache expiry: If the cache is expired or location data is missing, no geo attributes will be added.

Telemetry

This instrumentation adds the following OpenTelemetry Geo semantic convention attributes to spans and log records:

Attribute	Description
geo.location.lat	Latitude of the geo location in WGS84
geo.location.lon	Longitude of the geo location in WGS84
geo.country.iso_code	Two-letter ISO Country Code (ISO 3166-1 alpha2)
geo.region.iso_code	Region ISO code (ISO 3166-2)
geo.locality.name	Locality name (city, town, village, etc.)
geo.postal_code	Postal code associated with the location

Not implemented

geo.continent.code is not currently implemented.

Use Cases

• Geographic analysis: Understand where users are experiencing issues
• Regional debugging: Correlate performance or errors with specific locations
• Location-aware insights: Enrich telemetry with context for support and analytics