Skip to content
anecticoDocs
Console
Browse documentation
Guide

Capture errors and releases

Send actionable errors, keep grouping useful, and resolve production stack frames.

Read as Markdown ↗Use with an LLM ↗
On this page

Anectico groups similar error events into Issues. Good error context makes those Issues easier to prioritize and connects them to the customers and releases they affected.

Automatic grouping uses the error type, normalized message, and application stack frames. The message contributes once, after normalization. Stack headers and other non-frame lines, including exception-chain continuations such as Caused by:, are ignored. Runtime frames such as Node task-queue and timer internals are also ignored, so raw messages and concurrency-dependent async scheduling details do not split one application failure into multiple Issues. Browser frames are recognized in V8's at function (location) form, Firefox and Safari's function@location form, and the older two-line function then location form, so browser call sites do not fall back to stackless grouping.

Capture unexpected failures

Use your SDK's error method inside an existing error boundary. Continue to preserve the application's normal failure behavior.

JavaScript / TypeScript

try {
  await chargeCard();
} catch (error) {
  anectico.captureError(error as Error, {
    tags: { component: 'payments' },
  });
  throw error;
}

Python

try:
    charge_card()
except Exception as error:
    client.capture_error(error, tags={'component': 'payments'})
    raise

Go

if err := chargeCard(ctx); err != nil {
	client.CaptureError(ctx, err, anectico.WithTag("component", "payments"))
	return err
}

Swift (iOS)

do {
    try chargeCard()
} catch {
    Anectico.captureError(error, options: CaptureOptions(tags: ["component": "payments"]))
    throw error
}

Kotlin (Android)

try {
    chargeCard()
} catch (error: Exception) {
    Anectico.captureError(error, CaptureOptions(tags = mapOf("component" to "payments")))
    throw error
}

React Native

try {
  await chargeCard();
} catch (error) {
  await Anectico.captureError(error, { tags: { component: 'payments' } });
  throw error;
}

Flutter

try {
  await chargeCard();
} catch (error, stackTrace) {
  await Anectico.captureError(
    error,
    stackTrace,
    options: const CaptureOptions(tags: {'component': 'payments'}),
  );
  rethrow;
}

Do not capture expected validation failures as errors. Use a diagnostic event when the outcome is useful investigation context but does not require engineering action.

Add useful context

Prefer low-cardinality tags such as component, operation, or payment provider. Customer identity should come from the active identity context, not from a duplicate error tag.

SDKs encode capture tags into Anectico's indexed tag namespace automatically. Severity and handled and unhandled state appear with the issue when supplied. The issue proof page, which a link from your agent opens, shows the selected occurrence's severity, handling, mechanism, route, release and distribution, SDK and platform, device model, OS, and app version and build context when available. Use error.handled, error.mechanism, and app.route when an integration knows those values.

The native Android and iOS SDKs own their error and crash semantics. Caught errors are handled and nonfatal; uncaught exceptions and native crash paths are unhandled and fatal. Application tags cannot override those automatic values. The iOS runtime context is privacy-safe and does not collect a physical-device identifier.

Never attach passwords, authorization headers, access tokens, or unfiltered request bodies.

Set release and distribution

Every production build should send a stable release identifier. Use dist when the same release has multiple artifacts.

JavaScript / TypeScript

const anectico = await new AnecticoClient({
  apiKey: process.env.ANECTICO_API_KEY,
  serviceName: 'web',
  release: process.env.GIT_SHA,
  dist: 'browser',
}).start();

Python

client = anectico.AnecticoClient(
    api_key=os.environ['ANECTICO_API_KEY'],
    service_name='payments',
    service_version=os.environ['RELEASE'],
)

Go

client, err := anectico.New(
	anectico.WithAPIKey(os.Getenv("ANECTICO_API_KEY")),
	anectico.WithServiceName("payments"),
	anectico.WithServiceVersion(os.Getenv("RELEASE")),
	anectico.WithErrorRelease(os.Getenv("RELEASE")),
)

Swift (iOS)

Anectico.configure(AnecticoOptions(
    apiKey: apiKey,
    release: release,
    dist: buildNumber
))

Kotlin (Android)

Anectico.init(
    applicationContext,
    AnecticoOptions(apiKey = apiKey, release = release, dist = buildNumber),
)

React Native

await Anectico.configure({ apiKey, release, dist: buildNumber });

Flutter

await Anectico.configure(AnecticoOptions(
  apiKey: apiKey,
  release: release,
  dist: buildNumber,
));

Python currently uses the service version as the release identifier. In Go, WithErrorRelease sets the release for error occurrences and takes precedence over WithServiceVersion; when it is omitted, error tracking falls back to service.version. Neither SDK currently exposes a separate dist field. Keep the selected error release identical to the release registered by CI. Mobile and JavaScript integrations can additionally distinguish release-keyed symbol artifacts with dist. JavaScript source maps and Android ProGuard mappings use release and distribution keys. iOS dSYMs do not: each native frame matches a dSYM slice by exact Mach-O image UUID. Every symbol artifact belongs to the project it was uploaded to and is only used for that project's errors.

Upload symbols in CI

The Anectico CLI supports JavaScript source maps, Android ProGuard and R8 mappings, and iOS dSYMs.

anectico symbols upload-proguard mapping.txt --release "$RELEASE" --dist "$DIST"
anectico symbols upload-dsym MyApp.dSYM
anectico symbols upload-sourcemap --file sourcemap-upload.json

For iOS, pass either the .dSYM bundle or its exact Mach-O and DWARF file. Preserve the archive that produced the installed binary because matching uses its exact image UUID, not release or distribution. Symbol uploads require errors:write; add releases:write only when the CI job also registers a release. Each upload is attributed to the CLI's active project (--project or the selected profile project) and authenticated user and API key. Anectico commits a body-free audit record with the exact artifact keys, platform, project, actor, size, and SHA-256 in the same transaction as the artifact; source-map, mapping, and dSYM contents are never copied into audit metadata.

Upload one JavaScript source map per minified bundle, named by the bundle's path relative to the root it is served from (assets/app.js, or assets/app.js.map). Anectico matches a stack frame to the uploaded path that ends its URL path in whole directories: a frame from https://cdn.example.com/static/assets/app.js matches assets/app.js or static/assets/app.js, and the longest uploaded match wins. Two bundles with the same file name in different directories keep separate maps, and a map uploaded for one directory never resolves a frame from another. A bare file name (app.js) applies to that file in any directory. sourcemap-upload.json has this shape; the content value is the raw .map JSON encoded as a JSON string:

{
  "release": "web@2.4.1",
  "dist": "browser",
  "filename": "assets/app.js",
  "content": "{\"version\":3,\"sources\":[\"src/app.ts\"],\"names\":[],\"mappings\":\"\"}"
}

Run uploads after building and before deleting artifacts. Keep symbols private. JavaScript map content may be at most 8 MiB after JSON decoding. Because JSON string escaping can make the request file larger than the decoded map, use the dedicated upload-sourcemap command rather than an unrelated generic JSON-body command. The command injects the active project when project_id is not already present in the request file. Native upload limits are enforced separately. The issue proof page reports missing and mismatched JavaScript maps with the occurrence's exact release, distribution, and the bundle paths its frames were served from (required_filenames) while keeping raw bundled frames inspectable. Upload a map under one of those paths, or a shorter tail of it, to cover the frame. A mismatch means that an artifact exists but its release, distribution, path or mappings did not resolve the captured position; it does not mean symbolication succeeded.

Verify

Trigger one test error from a release build. Ask your agent for the issue (list_issues or get_issue over MCP, or anectico issues list and anectico issues view <issue-id>) and confirm the stack points to application source and that the affected customer and release are present. The get_issue result carries a link that opens the issue as a read-only proof page, with its stack trace, in the project named in the link.