이 페이지에는 Cloud의 URL이 표시됩니다. Dedicated에서 로그인하면 귀사 서버의 URL이 표시됩니다.

앱에 OTel 추가하기

세 단계로 Flutter 앱이나 Dart 서버에 Dartastic OpenTelemetry를 추가하세요. 패키지를 추가하고, 시작할 때 한 번 초기화하고, 빌드에 OTLP 엔드포인트와 토큰을 전달하면 됩니다. 트레이스, 로그, 메트릭이 Observatory에 도착합니다.

빌드DARTASTIC 아키텍처사용자토큰이슈Pub 토큰pushCI 토큰 교환앱 배포: 앱 스토어, 웹, 서버심볼크래시스택 트레이스소스 코드텔레메트리개발자 컴퓨터flutter run · dart pub getCIGitHub Actions, GitLab, …Control Room토큰 발급 · 역할 기반 접근 제어컨트롤 플레인조직 · 역할 · 토큰Dartastic Pub패키지 · 소스 코드Observatory세션 · 트레이스 · 로그Symbolizer크래시 → 소스 코드 줄Dartastic AI양쪽 데이터로 답변이슈 트래커GitHub · Jira · Linear모바일 + 데스크톱 앱휴대폰 · 태블릿 · 데스크톱OTLP 토큰으로 전송웹 앱브라우저에서 실행Browser OTLP 토큰으로 전송Dart 서버백엔드 · 서비스OTLP 토큰으로 전송

준비 사항

  • 알맞은 버전의 Flutter와 Dart. 첫 앱 만들기 문서에 패키지별 필요 버전이 나와 있습니다.
  • OTLP 토큰. Control Room에서 Tokens 화면을 열고 Generate, OTLP를 차례로 선택하세요. 토큰은 한 번만 표시되므로 비밀번호 관리자나 CI 시크릿에 보관하세요. Flutter 웹에서는 대신 Browser OTLP 토큰을 사용하세요(Browser OTLP).
  • OTLP 엔드포인트: https://otlp.cloud.dartastic.io.
  • 패키지를 위한 Dartastic Pub 접근 권한: Pub 토큰으로 dart pub token add https://pub.dartastic.io 명령을 실행하세요.
[TODO: Control Room의 “Tokens”: “Generate”, “OTLP”를 차례로 선택하면 새 토큰이 한 번 표시됩니다 스크린샷]

Flutter 앱

pubspec.yaml 파일에 두 패키지를 추가하세요. 두 패키지는 함께 릴리스되며 항상 같은 버전을 사용합니다.

yaml
dependencies:
  dartastic_opentelemetry_native:
    hosted: https://pub.dartastic.io
    version: 1.22.4
  dartastic_opentelemetry_native_flutter:
    hosted: https://pub.dartastic.io
    version: 1.22.4

runApp 호출 전에 한 번 초기화하세요.

dart
import 'package:dartastic_opentelemetry_native/dartastic_opentelemetry_native.dart';
import 'package:dartastic_opentelemetry_native_flutter/dartastic_opentelemetry_native_flutter.dart';
import 'package:flutter/material.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await DOTel.initialize(
    serviceName: 'checkout-app',
    serviceVersion: '1.4.0',
  );
  runApp(MaterialApp(
    navigatorObservers: [DartasticViewObserver()], // screen views
    home: const HomeScreen(),
  ));
}
  • serviceName 값은 Observatory에서 앱을 가리키는 이름입니다. 사람들이 알아볼 수 있는 이름을 고르세요. 패키지 이름과 같을 필요는 없습니다.
  • app.build_id 값은 앱의 빌드 식별자입니다. Flutter 패키지가 앱의 버전과 빌드 번호로 자동 설정합니다(빌드 ID). 크래시와 릴리스 비교가 이 값을 기준으로 그룹화됩니다.
  • DartasticViewObserver 옵저버는 경로가 푸시될 때마다 화면 조회를 기록하고, 각 화면이 열려 있던 시간을 기록합니다.

--dart-define 옵션으로 빌드에 엔드포인트와 토큰을 전달하세요. 휴대폰 앱은 셸의 환경 변수를 볼 수 없으므로 define을 통해 값을 전달합니다. 토큰을 소스 관리에 넣지 마세요. 로컬 머신이나 CI의 환경 변수에 두고 그 값을 전달하세요.

shell
flutter run --release \
  --dart-define=OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io \
  --dart-define=OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"

이것은 표준 OpenTelemetry 변수입니다. authorization 부분은 소문자로 쓰세요. 모든 프로토콜에서 작동합니다. OTLP 토큰은 귀사 조직으로 텔레메트리를 보내는 것만 가능하며, 아무것도 읽거나 변경하지 않습니다.

DOTel.initialize 호출이 끝나면 추가 코드 없이 다음을 기록합니다.

  • 방문마다 세션을 기록하며, 모든 스팬과 로그 레코드에 세션이 붙습니다.
  • 탭과 앱이 탭에 반응하는 속도.
  • DartasticViewObserver 옵저버를 통한 화면 조회.
  • 요금제에 포함된 경우 크래시, UI 멈춤, 버벅거림, Vitals 지표.

빌드 ID

빌드 ID는 각 플랫폼이 앱에 대해 보고하는 버전과 빌드 번호에서 만들어집니다.

앱 버전AndroidiOS
pubspec.yaml 파일의 version: 1.4.0+271.4.0+271.4.0+27
pubspec.yaml 파일의 version: 1.4.01.4.0+11.4.0
--build-name=1.4.0 --build-number=271.4.0+271.4.0+27

빌드 번호가 없는 버전에 Android는 +1 값을 붙입니다. 그것이 Android에서 Flutter의 기본 빌드 번호이기 때문입니다. 모든 플랫폼에서 같은 빌드 ID를 쓰려면 버전에 빌드 번호를 붙이세요(1.4.0+27).

Dart 서버

Dart 서버나 명령줄 앱에는 패키지 하나만 필요합니다.

yaml
dependencies:
  dartastic_opentelemetry_native:
    hosted: https://pub.dartastic.io
    version: 1.22.4
dart
import 'package:dartastic_opentelemetry_native/dartastic_opentelemetry_native.dart';

Future<void> main() async {
  await DOTel.initialize(
    serviceName: 'orders-api',
    serviceVersion: '2.3.1',
  );
  // ... start your server ...
}

서버에서는 같은 두 변수를 환경 변수에서 가져옵니다.

shell
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.cloud.dartastic.io
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $DARTASTIC_OTLP_TOKEN"
dart run bin/server.dart

텔레메트리가 앱을 망가뜨리지 않습니다

OpenTelemetry의 규칙에 따라 텔레메트리는 런타임에 코드로 오류를 던져서는 안 됩니다. Dartastic은 모든 곳에서 이 규칙을 따릅니다. 텔레메트리 내부에서 문제가 생기면(연결할 수 없는 엔드포인트, 잘못된 값을 가진 속성, 실패한 내보내기 등) 오류는 OpenTelemetry 오류 핸들러에 보고되고 로그로 남으며, 앱은 계속 실행됩니다.

이 보고를 직접 사용하는 로깅이나 크래시 보고 도구에서 보려면 핸들러를 직접 설치하세요. DOTel.initialize 호출 전후 어느 쪽에서 설치해도 작동합니다.

dart
// Before DOTel.initialize: send telemetry's own errors to your logging
// or crash reporting. OTel calls it instead of throwing into your code.
OTelAPI.setErrorHandler((error, stackTrace) {
  myLogger.warning('OpenTelemetry: $error', error, stackTrace);
});
  • 핸들러가 없으면 오류는 OpenTelemetry 자체 로그로 기록됩니다(OTEL_LOG_LEVEL 값으로 출력량을 정합니다).
  • 직접 만든 핸들러는 오류를 다시 던져도 되는 유일한 곳입니다. 예를 들어 테스트 빌드에서 빠르게 실패하게 할 때 씁니다. 프로덕션에서는 로그를 남기고 반환하세요.

도착 확인

앱을 실행해 1분 정도 사용한 뒤 Observatory의 “Traces”나 “Logs”를 여세요. serviceName 서비스가 표시됩니다(Observatory).

[TODO: 앱의 첫 트레이스를 보여 주는 Observatory의 “Traces” 화면 스크린샷]
보이는 현상해결 방법
아무것도 도착하지 않음엔드포인트를 확인하세요. --dart-define=OTEL_LOG_LEVEL=debug 옵션(서버에서는 OTEL_LOG_LEVEL=debug)을 넣어 한 번 실행하세요. 토큰이 앱에 전달되었다면 로그에 값을 가린 채 OTelEnv: Parsed 1 header(s) 메시지가 표시됩니다.
내보내기가 401로 거부됨토큰이 잘못되었거나, 폐기되었거나, 다른 조직이나 배포의 토큰입니다. 이 조직의 Control Room에서 새 OTLP 토큰을 생성하세요.
Flutter 웹에서 아무것도 보내지 않음웹에는 Browser OTLP 토큰이 필요하며, 그 토큰에 사이트의 출처(origin)를 등록해야 합니다(Browser OTLP).

전송량 조절

앱이 보내는 데이터는 Cloud와 Dedicated 모두에서 요금제의 수신 트래픽에 포함됩니다(가격). 트레이스, 메트릭, 로그는 기본적으로 켜져 있으며, 아래 값을 하나도 설정하지 않으면 샘플링으로 버려지는 데이터가 없습니다. RUM 화면 캡처는 기본적으로 꺼져 있습니다. 각 항목은 환경 변수로 설정할 수 있고, 앱 실행 중에 변경할 수도 있습니다. 언제 변경할지는 앱이 정하고 setter를 호출합니다. 원격 설정은 없습니다.

시그널환경 변수앱 실행 중
트레이스(Dart)OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARGDOTel.tracesSampler
트레이스(엔진)DARTASTIC_ENGINE_SAMPLER, DARTASTIC_ENGINE_SAMPLER_RATIO, DARTASTIC_ENGINE_SAMPLER_ERROR_UPDOTel.setEngineSampler()
로그DARTASTIC_LOGS_SAMPLE_RATEDOTel.logsSampleRate
메트릭DARTASTIC_METRICS_SAMPLE_RATEDOTel.metricsSampleRate
RUM 화면 캡처DARTASTIC_RUM_SAMPLE_RATEReplayCaptureController.setRumSampleRate()

휴대폰과 웹에서 환경 변수는 빌드할 때 설정하는 --dart-define 값입니다. 코드의 값이 환경 변수보다 우선하고, 앱 실행 중의 변경이 둘 다보다 우선합니다. 잘못된 값은 이름과 함께 OpenTelemetry 오류 핸들러로 전달되며, 기존에 적용되던 값이 유지됩니다.

  • 트레이스(엔진): 변경 사항은 다음 배치부터 적용됩니다. tail 샘플러가 아직 보관 중인 스팬은 즉시 새 샘플러를 거치므로, 변경해도 스팬을 잃지 않습니다.
  • 로그: 비율은 0.0~1.0이며 세션 단위로 결정됩니다. 세션은 통째로 유지되거나 버려지므로, 비율을 올리면 세션이 추가되기만 합니다. ERROR 이상의 레코드는 항상 전송되므로 크래시와 심각한 ANR은 반드시 도착합니다. 화면 조회와 탭은 로그 레코드이므로, 여기서 버려진 세션은 타임라인에 이들이 없습니다.
  • 메트릭: 비율은 0.0~1.0이며 내보내기 주기를 줄입니다. 0.25이면 주기 네 번 중 한 번만 전송합니다. 누적 합계는 정확하게 유지됩니다. DOTel.flushMetrics 호출과 종료 시에는 항상 전송하지만, 0이면 아무것도 보내지 않습니다.
  • RUM 화면 캡처: 비율은 0.0~1.0이며 세션 단위로 결정되고, 변경 사항은 즉시 적용됩니다. 비율을 올리면 세션이 추가되기만 하고, 내리면 제외되기만 합니다. 이 비율은 캡처가 기록하는 것에만 적용됩니다. 세션, 화면, 탭은 텔레메트리이므로 영향을 받지 않습니다. 지원용 녹화는 샘플링으로 버려지지 않습니다. 빌드와 코드가 모두 비율을 설정한다면 두 값이 같아야 하며, 다르면 캡처가 0에서 시작합니다. 캡처된 각 세션에 담기는 양은 충실도에 따라 정해집니다.

RUM 충실도

충실도는 리플레이에 화면이 얼마나 담기는지를 뜻합니다. 리플레이는 저장되는 바이트만큼 요금제의 수신 트래픽에 포함되므로, 수준을 낮추면 사용량도 줄어듭니다.

충실도리플레이에 보이는 내용1분당 추가량
Events화면, 탭, 네트워크 호출, 스팬, 오류, 크래시의 타임라인. 화면 이미지는 없습니다.리플레이 데이터 없음
Outline주요 요소마다 사각형 하나. 텍스트와 아이콘은 없습니다.62KB
Wireframe텍스트, 아이콘, 더 작은 컨트롤까지 각각 사각형으로 그립니다. 텍스트는 회색 막대로 표시되며, 글자는 기기를 떠나지 않습니다.81KB
Shadow텍스트를 읽을 수 없도록 블록 형태로 흐리게 처리한 실제 스크린샷.430KB
Pixel사용자가 본 그대로의 실제 스크린샷.597KB
Pixel, 입력한 텍스트 가림사용자가 입력한 내용을 덧칠해 가린 스크린샷.516KB
Pixel, 모든 텍스트 가림모든 텍스트를 덧칠해 가린 스크린샷.438KB

2026년 11월 Alpine Trails 데모 앱에서 측정했습니다. 5분 길이의 Pixel 세션은 약 3MB가 추가됩니다. 앱의 화면에 따라 결과는 달라집니다.

설정환경 변수앱 실행 중
앱의 수준DARTASTIC_RUM_FIDELITYReplayCaptureController.setFidelity()
개별 화면의 수준없음setFidelity(level, route: '/checkout')
빌드가 보낼 수 있는 최고 수준DARTASTIC_RUM_FIDELITY_MAX없음
Pixel에서 숨기는 텍스트없음ReplayCaptureController.setMasking()
리플레이 켜기/끄기없음ReplayCaptureController.setMode()

수준은 events, outline, wireframe, shadow, pixel입니다. 여기 나오는 각 환경 변수는 빌드할 때 설정하는 --dart-define 값입니다.

  • 앱의 수준: 빌드와 코드가 모두 설정한다면 두 값이 같아야 합니다. 다르거나 값이 올바른 수준이 아니면 캡처가 이를 보고하고 Events 수준에 머뭅니다. 지원용 녹화는 수준을 높일 수 있으며, 화면에 더 낮은 설정이 있으면 그 화면에서는 그 설정이 유지됩니다.
  • 최고 수준: 앱이나 녹화가 무엇을 요청하든, 엔진은 이 수준을 넘는 리플레이 레코드를 버립니다. 예를 들어 픽셀을 캡처할 수 없는 빌드임을 보증할 때 사용하세요.
  • Pixel에서 숨기는 텍스트: ReplayMasking.textFields 값은 사용자가 입력하는 내용을 숨기고, ReplayMasking.allText 값은 모든 텍스트를 숨깁니다.
  • 리플레이 켜기/끄기: 앱이 모드를 설정하기 전까지 리플레이는 꺼져 있습니다. ReplayMode.bufferUntilTrigger 모드는 프레임을 기기에 보관했다가 문제가 생겼을 때만 업로드하므로, 아무 문제 없는 세션은 리플레이를 전혀 업로드하지 않습니다.

웹뷰

결제 화면이나 고객센터처럼 앱 안의 웹 페이지가 오류, 요청, Web Vitals, 이벤트를 앱의 세션으로 보낼 수 있으며, 이 데이터에는 dartastic.telemetry.source webview 표시가 붙습니다. 페이지는 직접 내보내지 않고, 토큰을 갖지 않으며, 엔드포인트도 보지 못합니다. 페이지는 앱에 데이터를 넘기고, 앱이 모든 필드를 검사한 뒤 앱 자체의 파이프라인으로 보냅니다. 웹뷰 텔레메트리는 Pro 기능입니다.

신뢰하는 호스트를 지정하세요. 페이지의 호스트가 항목과 정확히 같거나 항목의 하위 도메인이면 일치하며, 목록이 비어 있으면 브리지가 꺼집니다.

dart
final bridge = DartasticWebviewBridge(
  allowedHosts: ['checkout.example.com', 'example.com'],
  serviceName: 'web-checkout',
  transport: DartasticWebviewTransport.javaScriptChannel,
);

허용된 페이지가 보내는 모든 데이터는 앱의 텔레메트리 자격 증명으로 전송되며, 서버에서 마스킹하지 않습니다. allowedHosts 목록과 브리지의 크기 제한이 유일한 안전장치입니다.

webview_flutter 사용 시 (4.9.0 이상)

dart
controller
  // Required on Android: without unrestricted JavaScript there is no
  // channel and no bridge.
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..addJavaScriptChannel(
    bridge.channelName,
    onMessageReceived: (m) => bridge.handleMessage(m.message),
  )
  ..setNavigationDelegate(NavigationDelegate(
    onPageStarted: (url) {
      final shim = bridge.shimForUrl(url);
      if (shim != null) controller.runJavaScript(shim);
    },
    // Required on iOS and macOS, and does nothing elsewhere.
    onPageFinished: (url) {
      final shim = bridge.shimForCommittedPage(url);
      if (shim != null) controller.runJavaScript(shim);
    },
  ));
// When the webview goes away:
bridge.notifyPageEnded();

flutter_inappwebview 사용 시 (6.1.5 이상)

브리지에 transport: DartasticWebviewTransport.inAppWebViewHandler 값을 설정하고, JavaScript는 켜 두세요.

dart
InAppWebView(
  initialUrlRequest: URLRequest(url: WebUri('https://checkout.example.com/')),
  // Installed once: it captures from document start, and holds what it
  // captures until the page is armed below.
  initialUserScripts: UnmodifiableListView([
    if (bridge.shimSource case final source?)
      UserScript(
        source: source,
        injectionTime: UserScriptInjectionTime.AT_DOCUMENT_START,
        forMainFrameOnly: true,
      ),
  ]),
  onWebViewCreated: (controller) {
    controller.addJavaScriptHandler(
      handlerName: bridge.channelName,
      callback: (args) =>
          bridge.handleMessage(args.isEmpty ? '' : args.first as String),
    );
  },
  onLoadStart: (controller, url) async {
    if (url == null) return;
    final source = bridge.shimForUrl(url.toString());
    if (source != null) {
      await controller.evaluateJavascript(source: source);
    }
  },
  // Required on iOS and macOS, and does nothing elsewhere.
  onPageCommitVisible: (controller, url) async {
    if (url == null) return;
    final source = bridge.shimForCommittedPage(url.toString());
    if (source != null) {
      await controller.evaluateJavascript(source: source);
    }
  },
)

도착하는 데이터

  • iOS와 macOS: 이 플랫폼에서는 shimForCommittedPage(1.32.0 이상)이 필요하며, 다른 플랫폼에서는 아무 동작도 하지 않습니다. 없으면 이 플랫폼의 페이지는 페이지 스팬만 보냅니다.
  • iOS와 macOS의 webview_flutter: 페이지 로드가 끝나기 전의 오류와 요청은 캡처되지 않으며, 로드가 끝나지 않는 페이지는 스팬만 보냅니다. Vitals 지표는 브라우저가 버퍼에 보관하므로 그래도 도착합니다. 이 데이터가 중요하다면 문서 시작부터 캡처하는 flutter_inappwebview 패키지를 사용하세요.
  • Web Vitals: TTFB와 FCP는 모든 플랫폼에서 도착합니다. LCP, CLS, INP와 긴 작업은 플랫폼이 측정하는 곳에서만 도착합니다. Android WebView는 네 가지를 모두 측정합니다. iOS 27의 WKWebView는 CLS와 긴 작업을 보고하지 않으며, LCP와 INP는 그곳에서 확인되지 않았습니다. 브리지는 값을 지어내지 않습니다.
  • 탭: 웹뷰나 지도 같은 플랫폼 뷰에 대한 탭은 기록되지만, 무반응 탭이나 분노 탭으로 집계되지 않습니다.