- 重要な情報
- はじめに
- 用語集
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
まだ RUM iOS SDK をインストールしていない場合は、アプリ内セットアップ手順に従うか、RUM iOS セットアップドキュメントを参照してください。
iOS RUM は、ユーザーアクティビティ、画面、エラー、ネットワークリクエストなどの属性を自動的に追跡します。RUM イベントおよびデフォルト属性については、RUM データ収集ドキュメントをご参照ください。カスタムイベントを追跡することで、ユーザーセッション情報を充実させ、収集された属性をより細かく制御することが可能になります。
ビューを自動追跡するほか、viewControllers
などの特定のさまざまなビューがインタラクティブに確認できるようになると追跡することも可能になります。ビューが確認できなくなったら、Global.rum
で以下のメソッドを使用して追跡を停止します。
.startView(viewController:)
.stopView(viewController:)
例:
// `UIViewController` で:
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
Global.rum.startView(viewController: self)
}
override func viewDidDisappear(_ animated: Bool) {
super.viewDidDisappear(animated)
Global.rum.stopView(viewController: self)
}
// in your `UIViewController`:
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
[DDGlobal.rum startViewWithViewController:self name:nil attributes:nil];
}
- (void)viewDidDisappear:(BOOL)animated {
[super viewDidDisappear:animated];
[DDGlobal.rum stopViewWithViewController:self attributes:nil];
}
DDRUMMonitor
クラスで詳細およびその他のオプションをご確認ください。
RUM のデフォルト属性に加えて、addTiming(name:)
API を使用して、アプリケーションが時間を費やしている場所を測定できます。タイミング測定は、現在の RUM ビューの開始を基準にしています。
たとえば、ヒーロー画像が表示されるまでにかかる時間を計ることができます。
func onHeroImageLoaded() {
Global.rum.addTiming(name: "hero_image")
}
- (void)onHeroImageLoad {
[DDGlobal.rum addTimingWithName:@"hero_image"];
}
一度設定したタイミングは @view.custom_timings.<timing_name>
としてアクセス可能です。例えば、@view.custom_timings.hero_image
のようになります。
ダッシュボードで視覚化を作成するには、まずメジャーの作成を行います。
アクションを自動的に追跡することに加えて、addUserAction(type:name:)
API を使って、特定のカスタムユーザーアクション (タップ、クリック、スクロール) を追跡することができます。
Global.rum
に .tap
のような瞬間的な RUM アクションを手動で登録するには、 .addUserAction(type:name:)
を使用します。.scroll
のような連続した RUM アクションを登録するには、.startUserAction(type:name:)
または .stopUserAction(type:)
を使用します。
例:
// `UIViewController` で:
@IBAction func didTapDownloadResourceButton(_ sender: UIButton) {
Global.rum.addUserAction(
type: .tap,
name: sender.currentTitle ?? "",
)
}
- (IBAction)didTapDownloadResourceButton:(UIButton *)sender {
NSString *name = sender.currentTitle ? sender.currentTitle : @"";
[DDGlobal.rum addUserActionWithType:DDRUMUserActionTypeTap name:name attributes:@{}];
}
注: .startUserAction(type:name:)
と .stopUserAction(type:)
を使用する場合、アクション type
は同じである必要があります。これは、RUM iOS SDK がアクションの開始と完了を一致させるために必要です。
DDRUMMonitor
クラスで詳細およびその他のオプションをご確認ください。
リソースを自動追跡するほか、ネットワークリクエストやサードパーティプロバイダ API などの特定のカスタムリソースを追跡することも可能です。RUM リソースを手動で収集するには、Global.rum
で次のメソッドを使用します。
.startResourceLoading(resourceKey:request:)
.stopResourceLoading(resourceKey:response:)
.stopResourceLoadingWithError(resourceKey:error:)
.stopResourceLoadingWithError(resourceKey:errorMessage:)
例:
// ネットワーククライアントで:
Global.rum.startResourceLoading(
resourceKey: "resource-key",
request: request
)
Global.rum.stopResourceLoading(
resourceKey: "resource-key",
response: response
)
// ネットワーククライアントで:
[DDGlobal.rum startResourceLoadingWithResourceKey:@"resource-key"
request:request
attributes:@{}];
[DDGlobal.rum stopResourceLoadingWithResourceKey:@"resource-key"
response:response
attributes:@{}];
注: 両方の呼び出しで resourceKey
に使用される String
は、呼び出すリソースに対して一意である必要があります。これは、RUM iOS SDK がリソースの開始と完了を一致させるために必要です。
DDRUMMonitor
クラスで詳細およびその他のオプションをご確認ください。
特定のエラーを追跡するには、エラーが発生したときにメッセージ、ソース、例外、追加属性で Global.rum
に通知します。エラー属性ドキュメントをご参照ください。
Global.rum.addError(message: "error message.")
[DDGlobal.rum addErrorWithMessage:@"error message." source:DDRUMErrorSourceCustom stack:nil attributes:@{}];
詳細と使用可能なオプションについては、DDRUMMonitor
クラスのコードドキュメントのコメントを参照してください。
RUM iOS SDK が自動的に取得するデフォルトの RUM 属性に加えて、RUM イベントにカスタム属性などのコンテキスト情報を追加して、Datadog 内の観測可能性を高めることができます。
カスタム属性を使用すると、観察されたユーザーの行動に関する情報 (カート値、マーチャント層、広告キャンペーンなど) をコードレベルの情報 (バックエンドサービス、セッションタイムライン、エラーログ、ネットワークヘルスなど) でフィルタリングおよびグループ化することができます。
カスタムグローバル属性を設定するには、Global.rum.addAttribute(forKey:value:)
を使用します。
Global.rum.addAttribute(forKey: "some key", value: "some value")
を使用します。Global.rum.addAttribute(forKey: "some key", value: "some other value")
を使用します。Global.rum.removeAttribute(forKey: "some key")
を使用します。RUM セッションにユーザー情報を追加すると、次のことが簡単になります。
以下の属性は任意で、少なくとも 1 つ提供する必要があります。
属性 | タイプ | 説明 |
---|---|---|
usr.id | 文字列 | 一意のユーザー識別子。 |
usr.name | 文字列 | RUM UI にデフォルトで表示されるユーザーフレンドリーな名前。 |
usr.email | 文字列 | ユーザー名が存在しない場合に RUM UI に表示されるユーザーのメール。Gravatar をフェッチするためにも使用されます。 |
ユーザーセッションを識別するには、setUserInfo(id:name:email:)
API を使用します。例:
例:
Datadog.setUserInfo(id: "1234", name: "John Doe", email: "john@doe.com")
[DDDatadog setUserInfoWithId:@"1234" name:@"John Doe" email:@"john@doe.com" extraInfo:@{}];
ライブラリを初期化するよう Datadog のコンフィギュレーションを作成する際、Datadog.Configuration.Builder
で以下のメソッドを使用できます。
set(endpoint: DatadogEndpoint)
set(batchSize: BatchSize)
.small
、.medium
、.large
などです。set(uploadFrequency: UploadFrequency)
.frequent
、.average
、.rare
などです。set(mobileVitalsFrequency: VitalsFrequency)
.frequent
(100ms 毎)、.average
(500ms 毎)、.rare
(1s 毎)、.never
(バイタル監視を無効にする)enableRUM(_ enabled: Bool)
set(rumSessionsSamplingRate: Float)
rumSessionsSamplingRate
の値は 0.0
~100.0
の間である必要があります。0.0
はセッションが送信されないこと、100.0
はすべてのセッションが Datadog に送信されることを意味します。構成されない場合、デフォルト値の 100.0
が使用されます。trackUIKitRUMViews(using predicate: UIKitRUMViewsPredicate)
UIViewControllers
の RUM ビューとしての追跡を有効にします。パラメーター (trackUIKitRUMViews()
) なしでこの API を呼び出して predicate
のデフォルト実装を使用するか、アプリに合わせてカスタマイズした独自の UIKitRUMViewsPredicate
を実装します。trackUIKitRUMActions(using predicate: UIKitRUMUserActionsPredicate)
trackUIKitRUMActions()
) なしでこの API を呼び出して predicate
のデフォルト実装を使用するか、アプリに合わせてカスタマイズした独自の UIKitRUMUserActionsPredicate
を実装します。trackURLSession(firstPartyHosts: Set<String>)
URLSession
タスク(ネットワークリクエスト)の RUM リソースとしての追跡を有効にします。パラメーター firstPartyHosts
は、first-party
リソース (RUM 機能が有効な場合) としてカテゴライズされ、挿入されるトレース情報を持つ(トレース機能が有効な場合)ホストを定義します。setRUMViewEventMapper(_ mapper: @escaping (RUMViewEvent) -> RUMViewEvent)
setRUMResourceEventMapper(_ mapper: @escaping (RUMResourceEvent) -> RUMResourceEvent?)
setRUMActionEventMapper(_ mapper: @escaping (RUMActionEvent) -> RUMActionEvent?)
setRUMErrorEventMapper(_ mapper: @escaping (RUMErrorEvent) -> RUMErrorEvent?)
setRUMLongTaskEventMapper(_ mapper: @escaping (RUMLongTaskEvent) -> RUMLongTaskEvent?)
setRUMResourceAttributesProvider(_ provider: @escaping (URLRequest, URLResponse?, Data?, Error?) -> [AttributeKey: AttributeValue]?)
provider
クロージャーが呼び出されます。このクロージャーはタスク情報と共に呼び出され、カスタムリソース属性を返すか、属性がアタッチされない場合は nil
を返します。enableLogging(_ enabled: Bool)
enableTracing(_ enabled: Bool)
setSpanEventMapper(_ mapper: @escaping (SpanEvent) -> SpanEvent)
ビューを自動的に追跡するには (UIViewControllers
)、RUM iOS SDK の構成時に .trackUIKitRUMViews()
オプションを使用します。デフォルトで、ビューの名前はビューコントローラーのクラス名になります。カスタマイズするには、.trackUIKitRUMViews(using: predicate)
を使用して、UIKitRUMViewsPredicate
プロトコルに準拠する predicate
の独自の実装を提供します。
public protocol UIKitRUMViewsPredicate {
func rumView(for viewController: UIViewController) -> RUMView?
}
@objc
public protocol DDUIKitRUMViewsPredicate: AnyObject {
func rumView(for viewController: UIViewController) -> DDRUMView?
}
rumView(for:)
実装内で、アプリは特定の UIViewController
インスタンスが RUM ビューを開始 (値を返す) またはしない (nil
を返す) ことを決定する必要があります。RUMView
の戻り値は name
を指定する必要があり、作成された RUM ビューに追加の attributes
を提供する場合があります。
たとえば、述語を構成して、アプリの各ビューコントローラーに明示的なタイプチェックを使用できます。
class YourCustomPredicate: UIKitRUMViewsPredicate {
func rumView(for viewController: UIViewController) -> RUMView? {
switch viewController {
case is HomeViewController: return .init(name: "Home")
case is DetailsViewController: return .init(name: "Details")
default: return nil
}
}
}
@interface YourCustomPredicate : NSObject<DDUIKitRUMViewsPredicate>
@end
@implementation YourCustomPredicate
- (DDRUMView * _Nullable)rumViewFor:(UIViewController * _Nonnull)viewController {
if ([viewController isKindOfClass:[HomeViewController class]]) {
return [[DDRUMView alloc] initWithName:@"Home" attributes:@{}];
}
if ([viewController isKindOfClass:[DetailsViewController class]]) {
return [[DDRUMView alloc] initWithName:@"Details" attributes:@{}];
}
return nil;
}
@end
アプリのアーキテクチャに基づき、さらに動的なソリューションを使用することも可能です。
たとえば、ビューコントローラーが一定して accessibilityLabel
を使用する場合、アクセシビリティラベルの値別にビューに名前を付けることができます。
class YourCustomPredicate: UIKitRUMViewsPredicate {
func rumView(for viewController: UIViewController) -> RUMView? {
guard let accessibilityLabel = viewController.accessibilityLabel else {
return nil
}
return RUMView(name: accessibilityLabel)
}
}
@interface YourCustomPredicate : NSObject<DDUIKitRUMViewsPredicate>
@end
@implementation YourCustomPredicate
- (DDRUMView * _Nullable)rumViewFor:(UIViewController * _Nonnull)viewController {
if (viewController.accessibilityLabel) {
return [[DDRUMView alloc] initWithName:viewController.accessibilityLabel attributes:@{}];
}
return nil;
}
@end
注: RUM iOS SDK は、アプリの実行中に何度も rumView(for:)
を呼び出します。実装をすばやく、シングルスレッドにすることをおすすめします。
ユーザーのタップ操作を自動的に追跡するには、RUM iOS SDK を構成するときに .trackUIKitActions()
オプションを使用します。
リソース (ネットワークリクエスト) を自動追跡し、最初の 1 バイトまでまたは DNS 解決などのタイミング情報を取得するには、RUM iOS SDK の構成時に .trackURLSession()
オプションを使用して、監視する URLSession
に DDURLSessionDelegate
を設定します。
let session = URLSession(
configuration: .default,
delegate: DDURLSessionDelegate(),
delegateQueue: nil
)
NSURLSession *session = [NSURLSession sessionWithConfiguration:[NSURLSessionConfiguration defaultSessionConfiguration]
delegate:[[DDNSURLSessionDelegate alloc] init]
delegateQueue:nil];
また、.trackURLSession(firstPartyHosts:)
を使用してファーストパーティホストを構成することも可能です。これにより、RUM で一致する特定のドメインを “first party” と分類し、トレース情報をバックエンドに伝播します(トレーシング機能が有効の場合)。ネットワークトレースは、調整可能なサンプリングレートでサンプリングされます。デフォルトでは、20% のサンプリングが適用されます。
たとえば、example.com
をファーストパーティホストとして構成し、RUM およびトレース機能の両方を有効にします。
Datadog.initialize(
// ...
configuration: Datadog.Configuration
.builderUsing(/* ... */)
.trackUIKitRUMViews()
.trackURLSession(firstPartyHosts: ["example.com"])
.set(tracingSamplingRate: 20)
.build()
)
Global.rum = RUMMonitor.initialize()
Global.sharedTracer = Tracer.initialize()
let session = URLSession(
configuration: .default,
delegate: DDURLSessionDelegate(),
delegateQueue: nil
)
これにより、インスツルメントされた session
と共に送信されたすべてのリクエストが追跡されます。example.com
ドメインに一致するリクエストは “first party” とマークされ、トレース情報がバックエンドに送信されて RUM リソースがトレースに接続されます。
DDConfigurationBuilder *builder = [DDConfiguration builderWithRumApplicationID:@"<rum_application_id>"
clientToken:@"<client_token>"
environment:@"<environment_name>"];
// ...
[builder trackUIKitRUMViews];
[builder trackURLSessionWithFirstPartyHosts:[NSSet setWithArray:@[@"example.com"]]];
[builder setWithTracingSamplingRate:20];
DDGlobal.rum = [[DDRUMMonitor alloc] init];
DDGlobal.sharedTracer = [[DDTracer alloc] initWithConfiguration:[DDTracerConfiguration new]];
[DDDatadog initializeWithAppContext:[DDAppContext new]
trackingConsent:trackingConsent
configuration:[builder build]];
カスタム属性をリソースに追加するには、RUM iOS SDK の構成時に .setRUMResourceAttributesProvider(_ :)
オプションを使用します。属性を提供するクロージャーを設定することで、追跡したリソースに追加の属性をアタッチして返すことができます。
たとえば、HTTP リクエストと応答ヘッダーを RUM リソースに追加できます。
.setRUMResourceAttributesProvider { request, response, data, error in
return [
"request.headers" : redactedHeaders(from: request),
"response.headers" : redactedHeaders(from: response)
]
}
Logger
と送信されたすべての “error” および “critical” ログは自動的に RUM エラーとして報告され、現在の RUM ビューにリンクされます。
let logger = Logger.builder.build()
logger.error("message")
logger.critical("message")
DDLogger *logger = [[DDLogger builder] build];
[logger error:@"message"];
[logger critical:@"message"];
同様に、エラーとしてマークされたすべての終了スパンは、RUM エラーとして報告されます。
let span = Global.sharedTracer.startSpan(operationName: "operation")
// ... `error` をキャプチャ
span.setError(error)
span.finish()
// ... capture the `error`
id<OTSpan> span = [DDGlobal.sharedTracer startSpan:@"operation"];
[span setError:error];
[span finish];
Datadog に送信される前に RUM イベントの属性を変更したり、イベントを完全に削除したりするには、RUM iOS SDK を構成するときに Event Mappers API を使用します。
Datadog.Configuration
.builderUsing(...)
.setRUMViewEventMapper { viewEvent in
return viewEvent
}
.setRUMErrorEventMapper { errorEvent in
return errorEvent
}
.setRUMResourceEventMapper { resourceEvent in
return resourceEvent
}
.setRUMActionEventMapper { actionEvent in
return actionEvent
}
.setRUMLongTaskEventMapper { longTaskEvent in
return longTaskEvent
}
.build()
DDConfigurationBuilder *builder = [DDConfiguration builderWithRumApplicationID:@"<rum_application_id>"
clientToken:@"<client_token>"
environment:@"<environment_name>"];
[builder setRUMViewEventMapper:^DDRUMViewEvent * _Nonnull(DDRUMViewEvent * _Nonnull viewEvent) {
return viewEvent;
}];
[builder setRUMErrorEventMapper:^DDRUMErrorEvent * _Nullable(DDRUMErrorEvent * _Nonnull errorEvent) {
return errorEvent;
}];
[builder setRUMResourceEventMapper:^DDRUMResourceEvent * _Nullable(DDRUMResourceEvent * _Nonnull resourceEvent) {
return resourceEvent;
}];
[builder setRUMActionEventMapper:^DDRUMActionEvent * _Nullable(DDRUMActionEvent * _Nonnull actionEvent) {
return actionEvent;
}];
[builder setRUMLongTaskEventMapper:^DDRUMLongTaskEvent * _Nullable(DDRUMLongTaskEvent * _Nonnull longTaskEvent) {
return longTaskEvent;
}];
[builder build];
各マッパーは (T) -> T?
というシグネチャを持つ Swift のクロージャで、 T
は具象的な RUM イベントの型です。これは、送信される前にイベントの一部を変更することができます。
例えば、RUM Resource の url
に含まれる機密情報をリダクティングするには、カスタム redacted(_:) -> String
関数を実装して、 RUMResourceEventMapper
で使用します。
.setRUMResourceEventMapper { resourceEvent in
var resourceEvent = resourceEvent
resourceEvent.resource.url = redacted(resourceEvent.resource.url)
return resourceEvent
}
[builder setRUMResourceEventMapper:^DDRUMResourceEvent * _Nullable(DDRUMResourceEvent * _Nonnull resourceEvent) {
resourceEvent.resource.url = redacted(resourceEvent.resource.url);
return resourceEvent;
}];
エラー、リソース、またはアクションマッパーから nil
を返すと、イベントが完全にドロップされます。イベントは Datadog に送信されません。ビューイベントマッパーから返された値は nil
であってはなりません(ビューをドロップするには、UIKitRUMViewsPredicate
の実装をカスタマイズします。詳しくは、ビューの自動追跡を参照してください)。
イベントのタイプに応じて、一部の特定のプロパティのみを変更できます。
イベントタイプ | 属性キー | 説明 |
---|---|---|
RUMViewEvent | viewEvent.view.name | ビューの名前。 |
viewEvent.view.url | ビューの URL。 | |
RUMActionEvent | actionEvent.action.target?.name | アクションの名前。 |
actionEvent.view.url | このアクションにリンクされているビューの URL。 | |
RUMErrorEvent | errorEvent.error.message | エラーメッセージ。 |
errorEvent.error.stack | エラーのスタックトレース。 | |
errorEvent.error.resource?.url | エラーが参照するリソースの URL。 | |
errorEvent.view.url | このエラーにリンクされているビューの URL。 | |
RUMResourceEvent | resourceEvent.resource.url | リソースの URL。 |
resourceEvent.view.url | このリソースにリンクされているビューの URL。 |
GDPR 規制を遵守するため、RUM iOS SDK は初期化時に追跡に関する同意を求めます。
trackingConsent
設定は以下のいずれかの値で示されます。
.pending
: RUM iOS SDK はデータの収集とバッチ処理を開始しますが、Datadog へは送信しません。RUM iOS SDK はバッチ処理が完了したデータをどうするかについての新たな同意値が得られるまで待機します。.granted
: RUM iOS SDK はデータの収集を開始し、Datadog へ送信します。.notGranted
: RUM iOS SDK はデータを収集しません。ログ、トレース、RUM イベントは Datadog に送信されません。RUM iOS SDK の初期化後に追跡同意値を変更するには、Datadog.set(trackingConsent:)
API 呼び出しを使用します。RUM iOS SDK は、新しい値に応じて動作を変更します。
たとえば、現在の追跡同意が .pending
の場合:
.granted
に変更すると、RUM iOS SDK は現在および今後のすべてのデータを Datadog に送信します。.notGranted
に変更すると、RUM iOS SDK は現在のすべてのデータを消去し、今後のデータを収集しません。アプリケーションが Datadog RUM に送信するデータを制御するには、RUM iOS SDK を初期化し、RUM セッションのサンプリングレートを 0~100 の間に指定します。
たとえば、セッションの使用の 50% のみを維持するには、
Datadog.initialize(
// ...
configuration: Datadog.Configuration
.builderUsing(/* ... */)
.set(rumSessionsSamplingRate: 50.0)
// ...
.build()
)
DDConfigurationBuilder *builder = [DDConfiguration builderWithRumApplicationID:@"<rum_application_id>"
clientToken:@"<client_token>"
environment:@"<environment_name>"];
// ...
[builder setWithRumSessionsSamplingRate:50];
[DDDatadog initializeWithAppContext:[DDAppContext new]
trackingConsent:trackingConsent
configuration:[builder build]];
RUM では、ユーザーのデバイスがオフラインのときにもデータを確実に利用できます。ネットワークの状態が悪いエリアやデバイスのバッテリーが非常に少ないなどの場合でも、すべての RUM イベントは最初にローカルデバイスにバッチで格納されます。ネットワークが利用可能で、RUM iOS SDK がエンドユーザーのエクスペリエンスに影響を与えないようにバッテリーの残量が十分にあれば、バッチはすぐに送信されます。アプリケーションがフォアグラウンドにあるときにネットワークが利用できない場合、またはデータのアップロードが失敗した場合、バッチは正常に送信されるまで保持されます。
つまり、ユーザーがオフラインでアプリケーションを開いても、データが失われることはありません。
注: ディスク上のデータは、古すぎる場合は RUM iOS SDK がディスク容量を使いすぎないようにするために自動的に破棄されます。
アプリがカスタムプロキシの後ろにあるデバイスで実行されている場合、RUM iOS SDK のデータアップローダーに通知して、すべてのトラッキングデータが関連するコンフィギュレーションでアップロードされるようにすることができます。
RUM iOS SDK の初期化時に、プロキシコンフィギュレーションにて指定します。
Datadog.initialize(
// ...
configuration: Datadog.Configuration
.builderUsing(/* ... */)
.set(proxyConfiguration: [
kCFNetworkProxiesHTTPEnable: true,
kCFNetworkProxiesHTTPPort: 123,
kCFNetworkProxiesHTTPProxy: "www.example.com",
kCFProxyUsernameKey: "proxyuser",
kCFProxyPasswordKey: "proxypass"
])
// ...
.build()
)
DDConfigurationBuilder *builder = [DDConfiguration builderWithRumApplicationID:@"<rum_application_id>"
clientToken:@"<client_token>"
environment:@"<environment_name>"];
// ...
[builder setWithProxyConfiguration:@{
(NSString *)kCFNetworkProxiesHTTPEnable: @YES,
(NSString *)kCFNetworkProxiesHTTPPort: @123,
(NSString *)kCFNetworkProxiesHTTPProxy: @"www.example.com",
(NSString *)kCFProxyUsernameKey: @"proxyuser",
(NSString *)kCFProxyPasswordKey: @"proxypass"
}];
[DDDatadog initializeWithAppContext:[DDAppContext new]
trackingConsent:trackingConsent
configuration:[builder build]];
詳しくは、URLSessionConfiguration.connectionProxyDictionary のドキュメントを参照してください。
お役に立つドキュメント、リンクや記事: