入门指南
从初识OpenTelemetry,到在Observatory中看到您自己的链路。每一步都建立在前一步之上,请按顺序进行。
关于OpenTelemetry
从OpenTelemetry开始
Dartastic基于OpenTelemetry(OTel)构建,这是记录软件运行情况的开放标准。Dartastic严格遵循OpenTelemetry规范:名称、数据和发送方式都是标准的。您学到的OpenTelemetry知识同样适用于Dartastic,用Dartastic构建的内容也始终是标准的OpenTelemetry。
这份规范并不难懂。继续之前,请花一小时阅读OpenTelemetry文档,建立基本了解:
- 什么是OpenTelemetry?
- 可观测性入门
- 信号,即下面介绍的三类数据
三种信号
OpenTelemetry记录三类数据,称为信号:
- 链路
- 发生了什么、按什么步骤进行,以及每一步耗时多久。一条链路是由Span组成的树:一次点击、它发起的网络调用、该调用背后的服务器处理,以及其下的数据库查询。一条链路可以从您的应用延伸到您的服务器。
- 指标
- 随时间测量的数值:帧时间、内存、每分钟请求数、每个版本的错误数。保存成本低,因此适合展示趋势和触发告警。
- 日志
- 带有时间和严重级别的文本行。在OpenTelemetry中,日志会带上写入时所处的链路,因此从一条日志就能打开同一时刻发生的其他所有事件。
三者都携带资源:由哪个应用发送、哪个版本、在哪台设备上。Dartastic在此之上增加了真实用户监控(会话、页面、点击和回放),同样以标准信号记录。概览解释了这些页面中使用的其他术语。
1. 登录
登录dartastic.io。首次登录时,您需要设置您的组织:您的令牌、团队成员和方案都归属于这个账号。如果是团队成员邀请了您,请使用受邀的邮箱地址登录,您将加入他们的组织。
注册后,您的组织从Cloud Free开始,无需信用卡。您需要提供:
- 组织名称和子域名:组织的名称,以及您的应用发送遥测数据的子域名。子域名永久归您所有。
- 区域:遥测数据的存储位置。日后无法更改。
- RUM上限:您的引擎可以记录的最高回放级别。Cloud Free最高到Wireframe;Shadow和Pixel包含在付费方案中。我们按您的选择生成引擎,设备上的任何操作都无法超出这一上限。
- Dartastic AI:使用您自己的模型密钥运行,您可以当时添加,也可以日后添加。
如果只使用Dartastic Pub,请在注册前在定价页面选择一个Pub方案。您只需为组织命名并选择区域,无需提供其他信息。
您将进入Control Room。Organization显示您组织的名称和ID。
2. 下载Reference Demo
点击Control Room顶部的Reference Demo,然后解压下载的文件。第5步会运行它:这是看到Dartastic实际效果的最快方式,其代码也展示了如何使用每项功能。进一步了解Reference Demo。
3. 将dart pub连接到您的Dartastic Pub
Dartastic的package来自您的Dartastic Pub,而不是pub.dev,dart pub需要令牌才能从中读取。大多数开发者从未做过这一步;每台电脑只需做一次,耗时一分钟。
Dartastic Pub同时也是pub.dev的直通代理。像往常一样在pubspec.yaml中声明您的package,来自pub.dev的package会自动从pub.dev解析,与Dartastic的package和您的私有package并存。
- 在Control Room中,前往Tokens:

- 生成Pub令牌:点击+ Pub。对话框随即打开:

- Name:任意能区分各个令牌的名称;我们建议使用
pub-org-read-write。 - Organization:此令牌要读取和发布哪个组织的package。
- Allow write (publish) access:勾选后即可用此令牌发布到您的Dartastic Pub。不勾选则令牌只能读取,这对Reference Demo已经足够,只有
symbolizer_demo_flutter和crash_demo_flutter例外,它们会发布到您的Pub。
- Name:任意能区分各个令牌的名称;我们建议使用
- 点击Generate。您的令牌只显示一次:
现在就用复制按钮复制令牌:关闭此对话框后,令牌无法再次显示。Granted scopes: Pub表示此令牌仅用于Pub:它不能发送遥测数据,也不能调用任何其他服务。
- 在命令行中,将令牌提供给
dart pub:当它提示shelldart pub token add https://pub.dartastic.ioEnter secret token:时,粘贴令牌并按Enter。粘贴时提示符不会显示任何内容,这是正常的。它会回复:terminalEnter secret token: Requests to "https://pub.dartastic.io" will now be authenticated using the secret token. - 在Reference Demo的文件夹中,获取其package: 如果成功,说明您的Pub和令牌都可用。shell
flutter pub get
dart pub会为该主机保存令牌,并且只发送给该主机。Pub介绍了令牌的列出、替换和删除,以及发布。
Pub令牌能访问哪些package
Pub令牌能访问其所有者可以使用的package,仅此而已。
- 组织管理员可以访问组织中的所有package,他们的令牌也一样。
- 其他团队成员只能为已分配给他们的package生成令牌。由管理员为团队成员分配package。
角色说明见邀请团队成员,为组织成员分配package见Pub。
4. 让应用发送遥测数据
在Tokens中生成一个OTLP令牌,然后按OpenTelemetry的标准形式在shell中导出。authorization请保持小写:
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <your OTLP token>"5. 运行演示
确保Docker正在运行,然后从Reference Demo的文件夹启动天气演示,并选择一台设备:
tool/launch.sh weather_flutter点击获取天气。这次点击会启动一条链路,贯穿应用、天气API、其缓存和外部天气服务。
6. 在Observatory中查看
您的点击会在几秒内到达Observatory。应用中提供了指向所发送数据的链接:点击链接即可打开链路,查看每一步及其耗时。
下一步
- 构建您的第一个应用:每个package所需的Flutter和Dart版本。
- 邀请团队成员,应在他们首次登录之前完成。
- 为您的应用添加OTel:将Dartastic添加到您自己的应用。