Location Instrumentation

Generates: Span and Log Attributes (injected into every span and log record)

Attaches geolocation attributes to telemetry using a one-shot location fix with reverse geocoding. Cached for 1 hour to minimize battery impact.

How It Works

On first enable, the SDK requests a one-shot location fix from CLLocationManager at kCLLocationAccuracyHundredMeters. The raw coordinates are passed to Apple's CLGeocoder.reverseGeocodeLocation(_:) to resolve city, region, country, and postal code. The result is cached in memory and UserDefaults for 1 hour, then refreshed automatically while the app is in the foreground.

No third-party geolocation service is involved — all geocoding uses Apple's on-device APIs.

Requirements

Add the following key to your app's Info.plist — iOS requires this for the system to show a permission prompt:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your reason for needing location access</string>

That's all. The SDK calls requestWhenInUseAuthorization() and requests the location fix itself. If the user denies permission, location attributes are silently omitted — no error is thrown and no other telemetry is affected.

Configuration

Location instrumentation is opt-in (disabled by default).

Pulse.shared.initialize(
    endpointBaseUrl: "https://your-backend.com",
    apiKey: "your-api-key",
    instrumentations: { config in
        config.location { $0.enabled(true) }  // default: false
    }
)

Attributes Injected into Every Span and Log

Attribute	Description	Example	Always Present
geo.location.lat	Latitude (decimal degrees)	37.7749	⚠️ If permission granted
geo.location.lon	Longitude (decimal degrees)	-122.4194	⚠️ If permission granted
geo.country.iso_code	ISO 3166-1 alpha-2 country code	"US"	⚠️ If geocoding succeeds
geo.region.iso_code	ISO 3166-2 region code	"US-CA"	⚠️ If geocoding succeeds
geo.locality.name	City or locality name	"San Francisco"	⚠️ If geocoding succeeds
geo.postal_code	Postal / ZIP code	"94102"	⚠️ If geocoding succeeds

Important Notes

• Permission prompt: The SDK requests authorization itself — you do not call requestWhenInUseAuthorization(). You only need the Info.plist key so iOS allows the prompt to appear.
• Accuracy: kCLLocationAccuracyHundredMeters — coordinates are accurate to roughly 100 metres. Postal code and city resolution depend on Apple's geocoder accuracy.
• Background: Location is only refreshed while the app is in the foreground. Going to background pauses the refresh timer to save battery.
• Cache TTL: 1 hour. Within the cache period, all spans and logs use the same geo attributes. After TTL, the next foreground fix updates the cache.

Disabling Location Instrumentation

config.location { $0.enabled(false) }