Ichnois SDK for Dart

pub package License: MIT

Official Dart SDK for Ichnois. Real-time error monitoring, breadcrumb tracing, and telemetry aggregation for pure Dart applications, CLI utilities, servers, and backend workers.


Features

  • Automated Exception Capture: Intercept unhandled exceptions across isolates and asynchronous zones.
  • Seamless Ichnois Ingestion: Native compatibility with https://ichnois-h2jw.onrender.com without duplicate /api/api path bugs.
  • Dual Authentication: Emits X-Ichnois-Auth and X-Sentry-Auth on all outgoing envelopes.
  • Environment & Define Awareness: Automatic discovery of ICHNOIS_DSN, ICHNOIS_ENVIRONMENT, ICHNOIS_RELEASE, and ICHNOIS_DIST (with backward-compatible SENTRY_* fallback).
  • Pure Ichnois API: First-class Ichnois, IchnoisOptions, IchnoisBreadcrumb, and IchnoisId classes with 100% interoperability with existing Sentry ecosystem patterns.

Installation

Add ichnois to your pubspec.yaml:

dependencies:
  ichnois: ^1.0.0

Or run:

dart pub add ichnois

Quickstart

1. Initialization

Initialize the SDK as early as possible in your Dart entrypoint (e.g. bin/main.dart or lib/main.dart):

import 'package:ichnois/ichnois.dart';

Future<void> main() async {
  await Ichnois.init((options) {
    // Set your Ichnois project DSN
    options.dsn = 'https://YOUR_KEY@ichnois-h2jw.onrender.com/api/YOUR_PROJECT_ID';
    
    // Optional configuration
    options.environment = 'production';
    options.release = 'my-app@1.0.0';
    options.tracesSampleRate = 1.0;
  });

  // Your application code
  runMyApplication();
}

2. Capturing Exceptions

import 'package:ichnois/ichnois.dart';

try {
  riskyOperation();
} catch (exception, stackTrace) {
  final eventId = await Ichnois.captureException(
    exception,
    stackTrace: stackTrace,
  );
  print('Reported to Ichnois with event ID: $eventId');
}

3. Capturing Messages and Breadcrumbs

import 'package:ichnois/ichnois.dart';

// Record informative breadcrumbs
Ichnois.addBreadcrumb(
  IchnoisBreadcrumb(
    message: 'User authenticated successfully',
    category: 'auth',
    level: IchnoisLevel.info,
  ),
);

// Capture standalone events
await Ichnois.captureMessage(
  'Payment gateway latency spiked above 2000ms',
  level: IchnoisLevel.warning,
);

4. HTTP Client Tracing

Wrap your http.Client with IchnoisHttpClient to automatically generate breadcrumbs and trace headers:

import 'package:http/http.dart' as http;
import 'package:ichnois/ichnois.dart';

final client = IchnoisHttpClient(client: http.Client());

final response = await client.get(Uri.parse('https://api.example.com/data'));

Environment Variables & Dart Defines

The SDK automatically inspects the environment at runtime:

Variable Description
ICHNOIS_DSN The Data Source Name for your project (e.g. https://key@ichnois-h2jw.onrender.com/api/proj)
ICHNOIS_ENVIRONMENT Target environment (production, staging, development)
ICHNOIS_RELEASE Application release tag (e.g. my-app@1.0.0)
ICHNOIS_DIST Distribution identifier

You can also pass Dart defines during build/run:

dart run --define=ICHNOIS_DSN=https://key@ichnois-h2jw.onrender.com/api/proj bin/main.dart

License

Licensed under the MIT License.

Libraries

ichnois
Official Dart SDK for Ichnois crash reporting and telemetry monitoring.
ichnois_io
sentry
A pure Dart client for Sentry.io crash reporting.
sentry_io