Help & Setup

Getting Started

Every plan follows the same first steps.

All plans

1. Subscribe (compare plans) and name your organization in onboarding.
2. Mint tokens in the Control Room, on its Tokens page — at minimum a pub token so dart pub get can read your registry.
3. Use tokens Usage depends on the token type (all token types).

OTel and Hosted plans

Your private Dartastic Pub will get populated with dartastic_opentelemetry_native packages (3 for Dev, 5 for Pro including dart and flutter metrics) and 600 otel_* Dartastic Labs integration packages. (Another 50+ otel_* open source packages that Dartastic maintains are available on pub.dev).

Hosted plans

1. In onboarding you also choose your subdomain: your stack lives at <subdomain>.dartastic.io, with your private registry at pub.<subdomain>.dartastic.io and private Dartastic Symbolizer at symbolizer.<subdomain>.dartastic.io.
2. 5–15 minutes later the Hosted page flips from "brewing" to your live URLs. The org owner will receive a welcome email with the urls.
3. Point telemetry at your stack with an Dartastic Observatory OTLP token — see the Dartastic Observatory Guide.

Dartastic Pub — Private Pub Registry

Dartastic Pub is a private Dart package registry — the same tooling protocols as pub.dev. Unlike pub.dev, published packages are not available to the world. They do not appear in search and are not resolved by dart pub get. Read and publish access is controlled by the organization and per package. Reads are authenticated too: without a token.

Authenticate the Dart CLI (once per machine)

Mint a pub token on the Tokens page, then register it:

dart pub token add https://pub.dartastic.io

The token lands in your local Dart credential store. Never commit it.

Publish a private package

Point publish_to at your registry and publish. You're the admin on every package you create — add collaborators and per-package tokens from the Pub page.

# pubspec.yaml of the package you're publishing
name: my_private_package
version: 1.0.0
publish_to: https://pub.dartastic.io

# then:
#   dart pub publish

Read and publish from CI — no stored secret

Don't paste a personal token into your CI secrets. A GitHub Actions job proves which repository it is with its own OIDC token and trades it for a 15-minute registry token of your organization. Nothing is stored in GitHub, and there is nothing to rotate.

1. An organization owner or admin binds the repository on the Tokens page (CI access): the repository (owner/name), optionally one workflow file, a GitHub environment and a ref pattern such as refs/tags/v*, and the packages it may publish. No packages means read-only: the job can dart pub get and can never publish.
2. The workflow requests its OIDC token with permissions: id-token: write and exchanges it, naming your organization id. The token reads your organization's packages and publishes exactly the bound packages, under your organization.

Read-only (pull requests, tests):

# .github/workflows/ci.yml — read-only: dart pub get, never publish
on: [pull_request, push]
permissions:
  contents: read
  id-token: write          # lets the job request its OIDC token
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Exchange this job's GitHub identity for a 15-minute registry token
        env:
          DARTASTIC_ORG_ID: <your organization id>
        run: |
          set -euo pipefail
          OIDC=$(curl -sS --fail-with-body \
            -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://dartastic.io" | jq -er .value)
          RESP=$(curl -sS --fail-with-body -X POST https://api.dartastic.io/v1/ci/exchange \
            -H "Authorization: Bearer $OIDC" -H "Content-Type: application/json" \
            -d "{\"orgId\":\"$DARTASTIC_ORG_ID\"}") || { echo "$RESP" >&2; exit 1; }
          PUB_TOKEN=$(echo "$RESP" | jq -er .token)
          echo "::add-mask::$PUB_TOKEN"
          echo "PUB_TOKEN=$PUB_TOKEN" >> "$GITHUB_ENV"
      - uses: dart-lang/setup-dart@v1
      - run: dart pub token add https://pub.dartastic.io --env-var PUB_TOKEN
      - run: dart pub get        # flutter pub get works the same way
      - run: dart test

Publish (a release workflow):

# .github/workflows/publish.yml — publish the bound packages on a version tag
on:
  push:
    tags: ['v*']
permissions:
  contents: read
  id-token: write
jobs:
  publish:
    runs-on: ubuntu-latest
    environment: release     # bind the environment too: its reviewers gate publishing
    steps:
      - uses: actions/checkout@v4
      - name: Exchange this job's GitHub identity for a 15-minute registry token
        env:
          DARTASTIC_ORG_ID: <your organization id>
        run: |
          set -euo pipefail
          OIDC=$(curl -sS --fail-with-body \
            -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://dartastic.io" | jq -er .value)
          RESP=$(curl -sS --fail-with-body -X POST https://api.dartastic.io/v1/ci/exchange \
            -H "Authorization: Bearer $OIDC" -H "Content-Type: application/json" \
            -d "{\"orgId\":\"$DARTASTIC_ORG_ID\"}") || { echo "$RESP" >&2; exit 1; }
          PUB_TOKEN=$(echo "$RESP" | jq -er .token)
          echo "::add-mask::$PUB_TOKEN"
          echo "PUB_TOKEN=$PUB_TOKEN" >> "$GITHUB_ENV"
      - uses: dart-lang/setup-dart@v1
      - run: dart pub token add https://pub.dartastic.io --env-var PUB_TOKEN
      - run: dart pub publish --force

• A refused exchange names its reason, for example TRUSTED PUBLISHER NOT BOUND (no binding for this repository in that organization), TRUSTED PUBLISHER ENVIRONMENT MISMATCH or TRUSTED PUBLISHER REF MISMATCH (the run is outside what the binding allows), or CI OIDC AUDIENCE INVALID (request the token with audience=https://dartastic.io).
• Pull requests from forks get no OIDC token from GitHub, so they cannot exchange. That is GitHub's protection, and it is the right default.
• To cut a repository off, remove its binding. The next exchange is refused, and tokens already issued expire within 15 minutes.
• If a repository is deleted and recreated under the same name, the binding refuses it (TRUSTED PUBLISHER REPOSITORY ID MISMATCH). Remove the binding and add it again.

Build with symbols — automatic crash deobfuscation

Build obfuscated releases with --split-debug-info (native) or --source-maps (web) and keep the output inside the package you publish. The .symbols / .js.map files ride the published archive — publishing to your registry is the upload, so there is no separate release-time symbol-upload step to forget. Dartastic Symbolizer pulls the archive on demand, extracts the debug artifacts (matched by basename at any depth, keyed by app + version + platform), and turns obfuscated production stack traces into deobfuscated traces with real file-and-line references. Your symbols never leave your namespace.

# Build with symbols, then publish as usual:
flutter build apk  --release --obfuscate --split-debug-info=symbols/   # native
flutter build web  --release --source-maps                             # web

dart pub publish   # .symbols / .js.map ride the package archive

Make sure the symbols directory isn't excluded by .pubignore or .gitignore — if dart pub publish skips it, Dartastic Symbolizer has nothing to resolve that version's crashes against.

Before your first publish — requirements

A minimal proprietary LICENSE (for an OSS fork, copy the upstream license instead):

Copyright (c) <year> <Your Company>. All rights reserved.

This software is proprietary and confidential. Unauthorized copying,
distribution, or use of this package, in whole or in part, is prohibited
except as expressly permitted by a written agreement with <Your Company>.

Warnings, not blockers — publish proceeds after a y/N prompt:

• dart analyze issues
• missing homepage / repository
• missing CHANGELOG.md

Only a missing LICENSE is a hard stop — that's the Dart SDK, not Dartastic.

Troubleshooting publish & auth

• (no writable packages) — your token authenticated, but its team doesn't own this package (authorization, not authentication). Create or claim the package under your team on the Pub page, then re-mint the token after changing your team's packages.
• Authentication is required, please add authorization header — no token is stored for this host. Run the token add above. The host is pub.dartastic.io (not the old pub.dartastic.io).
• The Enter secret token: prompt is silent (no echo) — which is why we pipe the token with echo above instead of pasting into the prompt.

Browse, search, retract, audit

• Browse and search your packages at pub.dartastic.io.
• Retract versions any time — no 7-day window.
• Per-download audit trail: who pulled what, and when.

pubspec.yaml — adding the Pro packages

Open-source packages resolve from pub.dev as usual; private packages take an explicit hosted: URL pointing at your registry.

dependencies:
  # Open-source OTel API + SDK — from pub.dev, no auth required.
  dartastic_opentelemetry: ^1.1.0-beta.6

  # Pro SDK — from your Dartastic Pub registry.
  dartastic_opentelemetry_native:
    hosted: https://pub.dartastic.io
    version: ^1.0.0-beta.2

  # Flutter apps also add the engine-bundling plugin:
  dartastic_opentelemetry_native_flutter:
    hosted: https://pub.dartastic.io
    version: ^0.1.0-beta.1

Consuming doesn't require publishing anything — an app with publish_to: none still pulls private packages this way. It does require the pub token from the step above (reads are authenticated).

OTel SDK & Pro Engine

The Dartastic OTel SDK is two layers: the open-source dartastic_opentelemetry Dart SDK (Apache 2.0, on pub.dev) and the Pro SDK (dartastic_opentelemetry_native, on your Dartastic Pub). Pro adds the native Rust engine — off-isolate OTLP export with persistent queues, retry/backoff and circuit breaking, adaptive backpressure, smart sampling, PII scrubbing, crash + ANR detection, jank attribution, and direct-to-Dartastic Symbolizer crash deobfuscation.

There is no license key to paste. Your engine is built and licensed for your organization automatically when you subscribe; adding the package is the whole integration. Build status is visible on the OTel tab.

Initialize — one character

DOTel.initialize() replaces and fully includes the OSS OTel.initialize() — every OSS parameter (service name/version, resource attributes, span processors, samplers, metric and log exporters, platform resource detection, …) is accepted and passed straight through, so there is no second initialize call. On top of the OSS setup it loads the engine, verifies your org's license, wires the native span processor, and auto-registers the ANR / native-heap / vsync / jank instruments your build includes.

import 'package:dartastic_opentelemetry_native/dartastic_opentelemetry_native.dart';

// DOTel.initialize replaces the OSS OTel.initialize — a one-character
// change (O → DO). Every OSS parameter is accepted and passed through.
await DOTel.initialize(
  serviceName: 'my-app',
  endpoint: 'https://otlp.cloud.dartastic.io:443',
);

The full DOTelProConfig surface (retry, circuit breaker, sampling, compression, PII scrubbing, persistent queue, Dartastic Symbolizer forwarding) is documented in the dartastic_opentelemetry_native README on your registry.

Configuration enums

Where the OTel spec defines a value set, the SDK exposes it as a standard enum; where it doesn't, Dartastic defines one:

Surviving bad weather

The engine is designed to survive bad days. During a crash storm (thousands of identical exceptions in seconds) it deduplicates against a local cache — every span still ships with a symbolized stack, but Dartastic Symbolizer is only consulted once per unique trace. When your OTLP endpoint returns 429 Too Many Requests or 503 with a Retry-After header, the engine pauses sends until the deadline instead of hammering the wall, and the adaptive backpressure state machine (healthy → stressed → critical → throttled) scales sampling down before your users feel it as battery drain.

Environment-Variable Reference

The engine honors the standard OTel env vars plus DARTASTIC_* extras. Boolean-ish variables accept on / true / 1 / yes and off / false / 0 / no (case-insensitive); any other value falls back to the default with a warning — the SDK never fails on a bad env var.

Runtime = read from the OS environment at start. Compile-time = pass as --dart-define=NAME=value to flutter build / dart compile (these tree-shake disabled features out of release binaries).

Metrics — Flutter Apps and Dart Servers

Two companion packages turn on deep runtime metrics with one call each. Both live on your Dartastic Pub registry.

dependencies:
  # Flutter apps — frames, jank, startup, navigation, device state:
  dartastic_opentelemetry_flutter_metrics:
    hosted: https://pub.dartastic.io
    version: ^1.0.0-beta.9

  # Dart servers & CLIs — process, Linux server + container metrics:
  dartastic_opentelemetry_dart_metrics:
    hosted: https://pub.dartastic.io
    version: ^1.0.0-beta.2

• dartastic_opentelemetry_flutter_metrics — per-frame build/raster histograms with route + severity attribution, jank ratio, app-startup timing anchored on the real native process start, navigation timings, memory pressure, battery, thermal state, release health, and device + app resource attributes. One call: DartasticFlutterMetrics.start().
• dartastic_opentelemetry_dart_metrics — process CPU/memory/GC, plus Linux server and container (cgroup) metrics for Dart services in Docker/Kubernetes: load averages, iowait/steal, file-descriptor limits, cgroup memory and CPU-throttle counters. Works in AOT-compiled production binaries.

Every feature is individually opt-out-able — see the env-var reference; full metric tables are in each package's README on your registry.

Dartastic Symbolizer — Crashes to Source Lines

Dartastic Symbolizer turns obfuscated production stack traces into source-code lines, in any OTLP-compatible platform. No partner integration required — the Dartastic Native OTel Pro talks to Dartastic Symbolizer directly before shipping the exception event onward.

1 · Upload debug symbols at build time

After flutter build apk --obfuscate --split-debug-info=… (or the equivalent iOS / desktop build), publish the resulting .symbols files to your Dartastic Pub registry — they ride the package archive automatically (see Build with symbols in the Pub section), and Dartastic Symbolizer fetches them from there on demand. Each upload is scoped to package name + version + platform, and Dartastic Symbolizer uses that triple to pick the right symbols per crash.

2a · Shared Dartastic Symbolizer (Dartastic Symbolizer tier and OTel plans)

Mint a Dartastic Symbolizer token on the Tokens page and set SymbolizerMode.auto in the Pro SDK's SymbolizerConfig (or set DARTASTIC_CRASH_URL=https://symbolizer.dartastic.io + DARTASTIC_CRASH_API_KEY at deploy time). Symbols upload to the shared registry; crashes deobfuscate against the shared service.

2b · Hosted — your private Dartastic Symbolizer

Hosted stacks include a private Dartastic Symbolizer at symbolizer.<subdomain>.dartastic.io. The Dartastic Native SDK picks it up automatically; mint a Dartastic Hosted Symbolizer token for explicit configuration or CI use. Your symbols live on your registry, your crashes never touch shared infrastructure.

3 · On-prem (regulated workflows)

Compliance customers run Dartastic Symbolizer behind their own firewall so production traces never leave the perimeter — point the engine at it with SymbolizerMode.endpointOverride or the DARTASTIC_CRASH_URL override pair. Deobfuscation stays inside your network; only the readable OTLP event continues to your backend.

Alert Notifications on Your Box

Your box alerts out of the box: a default email contact point sends every alert to the address that subscribed, and the email transport is preconfigured. Everything below is optional tuning, done entirely in your box's UI under Alerting. Your configuration is yours; the platform never overwrites contact points or routes you create.

Contact points: where alerts go

Alerting › Notification configuration › Contact points. Create one per destination: email addresses, PagerDuty integration keys, or webhooks. Every contact point has a Test button; use it, it sends a real notification.

Slack

Create a Slack contact point, but do not paste your Slack webhook into the URL field directly. Instead, wrap it in your box's local notification proxy so messages arrive cleanly formatted and Dartastic-branded:

http://notification-sanitizer:8092/slack?to=<your URL-encoded Slack webhook>

URL-encode the webhook (in a shell: printf %s 'https://hooks.slack.com/services/...' | jq -sRr @uri). The proxy accepts only real hooks.slack.com/services/ destinations and runs inside your box; your webhook never leaves it.

Routing: which alerts go where

Two ways, both fully supported. Simplest: when you create an alert rule, pick a contact point right on the rule. For richer control, use Alerting › Notification configuration › Notification policies and add routes with label matchers. Routes you add are preserved across restarts and platform updates.

What the platform manages

Exactly two things: the Dartastic default email contact point (destination: your subscribing admin address) and a match-all fallback route to it, so an alert that matches none of your routes still reaches a human. Change where it delivers by creating your own contact points and routes above it; the fallback only catches what nothing else does.

Starter rules (included)

Notifications deliver alerts; alert rules decide when alerts exist. Your box ships with a starter set, in the Dartastic Alerts folder under Alerting › Alert rules, so it does something useful the moment a destination exists. They route through the default policy above, so the first crash reaches your inbox with no extra setup.

Watching your apps (the signals your apps report through the Dartastic OTel SDK):

• App error rate is elevated: error spans are climbing on a service.
• App crashes detected: a crashed session was recorded.
• No telemetry is arriving: spans stopped for over an hour, usually broken instrumentation.

Watching your box:

• Disk is almost full: the root filesystem is over 85%, so telemetry storage is at risk.
• CPU is saturated: over 90% for ten minutes.
• Memory is under pressure: over 90% for ten minutes.

The starter rules are read-only, and restored on every restart. To change a threshold, copy a rule to make your own editable version. Two things to expect: the app rules stay quiet until an app is reporting, and No telemetry is arriving fires on a brand-new box until your first app connects, so copy-and-pause it if you are not ready.

Add your own

Create more under Alerting › Alert rules: latency, business metrics, whatever matters to you. Pick a contact point right on the rule, or let the routing above carry it.

Tokens

Dartastic uses fine-grained tokens on the GitHub personal-access-token model: each token is minted for a purpose, shown once at mint time, and revocable independently. Mint and revoke on the Tokens page — you'll see a button for each token type your plan grants:

• Tokens are cryptographically signed and verified offline by each service — there's no central check in your request path, so a token outage can't take your builds down.
• Revocations propagate via a signed revocation list that every service polls — revoke on the Tokens page and walk away.
• Rotation is non-destructive: old and new tokens coexist while you redeploy.
• Pub tokens can be scoped to all your packages or a chosen subset (per-package read/publish).

Remember the echo-pipe when registering pub tokens — see Dartastic Pub.

Ingest tokens: browser or server — pick the right one

Telemetry ingest tokens come in two classes, and each is refused in the other's place. The token string itself gives no clue which class you hold, so this is worth getting right before you ship.

Both mismatches fail the same way, with the same status:

• A browser token in a mobile or server app never reports. Those clients send no Origin header, and a missing origin can never match the allowlist, so every export is refused at the edge.
• A server token in a web build never reports either, for the mirror-image reason: the browser adds an Origin to the request, and that is exactly what the server-token rule rejects.

Dartastic Observatory — Cloud & Hosted

Dartastic Observatory is native OpenTelemetry observability for Dart and Flutter — dashboards, metrics, traces, and logs, with Flutter-focused dashboards pre-loaded. It comes in two flavors: Cloud, the shared metered tier at cloud.dartastic.io, and Hosted, a dedicated single-tenant stack behind <subdomain>.dartastic.io.

Both include Dartastic AI, using your own model key: Cloud with a daily question limit, Hosted unlimited.

Migrating from Sentry — Drop-in DSNs

Hosted stacks accept Sentry SDK traffic directly, so you can move off Sentry without touching instrumentation code:

1. Open the Sentry DSNs tab (visible on Hosted plans) and mint a DSN per project.
2. Replace the DSN in your existing Sentry.init(…) call — that's the entire code change.
3. Your Sentry SDK events, transactions, and sessions now flow to your stack, translated into OpenTelemetry alongside everything else. Migrate to the Dartastic SDK at your own pace.

Dartastic Compliance — OTel Library Tier

Compliance is a library tier of the Dartastic OTel SDK — parallel to Pro, not part of Hosted. It adds regulated-workflow features in the SDK / Dartastic Native OTel Pro: audit trails, retention controls, signed spans, and the pieces needed for SOC 2 / HIPAA / FedRAMP-adjacent obligations. Compliance does not include hosting; pair it with your own OTLP platform, or with a Hosted tier for the full single-tenant story.

See Pricing for the full feature list and contact sales@dartastic.io for procurement details.