Catch up on highlights from Firebase at Google I/O 2023. Learn more

ปรับแต่งรายงานข้อขัดข้องของ Firebase Crashlytics

คู่มือนี้อธิบายวิธีปรับแต่งรายงานข้อขัดข้องโดยใช้ Firebase Crashlytics SDK ตามค่าเริ่มต้น Crashlytics จะรวบรวมรายงานข้อขัดข้องสำหรับผู้ใช้แอปทั้งหมดของคุณโดยอัตโนมัติ (คุณสามารถปิดการรายงานข้อขัดข้องอัตโนมัติและ เปิดใช้การรายงานข้อขัดข้อง สำหรับผู้ใช้ของคุณแทน) Crashlytics มีกลไกการบันทึกสี่แบบตั้งแต่แกะกล่อง: คีย์แบบกำหนดเอง บันทึกแบบกำหนดเอง ตัวระบุผู้ใช้ และ ข้อยกเว้นที่ตรวจจับได้

เพิ่มคีย์ที่กำหนดเอง

คีย์ที่กำหนดเองช่วยให้คุณทราบสถานะเฉพาะของแอปที่นำไปสู่การหยุดทำงาน คุณสามารถเชื่อมโยงคู่คีย์/ค่าตามอำเภอใจกับรายงานข้อขัดข้อง จากนั้นใช้คีย์ที่กำหนดเองเพื่อค้นหาและกรองรายงานข้อขัดข้องในคอนโซล Firebase

  • ใน แดชบอร์ด Crashlytics คุณสามารถค้นหาปัญหาที่ตรงกับคีย์ที่กำหนดเองได้
  • เมื่อคุณตรวจสอบปัญหาเฉพาะในคอนโซล คุณสามารถดูคีย์แบบกำหนดเองที่เกี่ยวข้องสำหรับแต่ละเหตุการณ์ (แท็บย่อย คีย์ ) และแม้แต่กรองเหตุการณ์ด้วยคีย์แบบกำหนดเอง (เมนู ตัวกรอง ที่ด้านบนของหน้า)

ใช้เมธอด setCustomValue เพื่อตั้งค่าคู่คีย์/ค่า ตัวอย่างเช่น:

สวิฟต์

// Set int_key to 100.
Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set str_key to "hello".
Crashlytics.crashlytics().setCustomValue("hello", forKey: "str_key")

วัตถุประสงค์-C

เมื่อตั้งค่าจำนวนเต็ม บูลีน หรือทศนิยม ให้ใส่กรอบค่าเป็น @( value )

// Set int_key to 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set str_key to "hello".
[[FIRCrashlytics crashlytics] setCustomValue:@"hello" forKey:@"str_key"];

คุณยังสามารถแก้ไขค่าของคีย์ที่มีอยู่ได้โดยการเรียกคีย์และตั้งค่าเป็นค่าอื่น ตัวอย่างเช่น:

สวิฟต์

Crashlytics.crashlytics().setCustomValue(100, forKey: "int_key")

// Set int_key to 50 from 100.
Crashlytics.crashlytics().setCustomValue(50, forKey: "int_key")

วัตถุประสงค์-C

[[FIRCrashlytics crashlytics] setCustomValue:@(100) forKey:@"int_key"];

// Set int_key to 50 from 100.
[[FIRCrashlytics crashlytics] setCustomValue:@(50) forKey:@"int_key"];

เพิ่มคู่คีย์/ค่าจำนวนมากโดยใช้เมธอด setCustomKeysAndValues ​​โดยมี NSDictionary เป็นพารามิเตอร์เดียว:

สวิฟต์

let keysAndValues = [
                 "string key" : "string value",
                 "string key 2" : "string value 2",
                 "boolean key" : true,
                 "boolean key 2" : false,
                 "float key" : 1.01,
                 "float key 2" : 2.02
                ] as [String : Any]

Crashlytics.crashlytics().setCustomKeysAndValues(keysAndValues)

วัตถุประสงค์-C

NSDictionary *keysAndValues =
    @{@"string key" : @"string value",
      @"string key 2" : @"string value 2",
      @"boolean key" : @(YES),
      @"boolean key 2" : @(NO),
      @"float key" : @(1.01),
      @"float key 2" : @(2.02)};

[[FIRCrashlytics crashlytics] setCustomKeysAndValues: keysAndValues];

เพิ่มข้อความบันทึกที่กำหนดเอง

หากต้องการให้บริบทเพิ่มเติมเกี่ยวกับเหตุการณ์ที่นำไปสู่การหยุดทำงาน คุณสามารถเพิ่มบันทึก Crashlytics ที่กำหนดเองลงในแอปของคุณได้ Crashlytics เชื่อมโยงบันทึกกับข้อมูลข้อขัดข้องของคุณและแสดงในหน้า Crashlytics ของ คอนโซล Firebase ใต้แท็บ บันทึก

สวิฟต์

ใช้ log() หรือ log(format:, arguments:) เพื่อช่วยระบุปัญหา หากคุณต้องการรับเอาต์พุตบันทึกที่เป็นประโยชน์พร้อมข้อความ ออบเจ็กต์ที่คุณส่งผ่านไปยัง log() จะต้องสอดคล้องกับคุณสมบัติ CustomStringConvertible log() ส่งคืนคุณสมบัติคำอธิบายที่คุณกำหนดสำหรับวัตถุ ตัวอย่างเช่น:

Crashlytics.crashlytics().log("Higgs-Boson detected! Bailing out…, \(attributesDict)")

.log(format:, arguments:) จัดรูปแบบค่าที่ส่งคืนจากการเรียก getVaList() ตัวอย่างเช่น:

Crashlytics.crashlytics().log(format: "%@, %@", arguments: getVaList(["Higgs-Boson detected! Bailing out…", attributesDict]))

สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับวิธีใช้ log() หรือ log(format:, arguments:) โปรดดูที่ เอกสารอ้างอิงของ Crashlytics

วัตถุประสงค์-C

ใช้ log หรือ logWithFormat เพื่อช่วยระบุปัญหา โปรดทราบว่าหากคุณต้องการรับเอาต์พุตบันทึกที่มีประโยชน์พร้อมข้อความ ออบเจ็กต์ที่คุณส่งผ่านไปยังเมธอดใดวิธีหนึ่งจะต้องแทนที่คุณสมบัติอินสแตนซ์ description ตัวอย่างเช่น:

[[FIRCrashlytics crashlytics] log:@"Simple string message"];

[[FIRCrashlytics crashlytics] logWithFormat:@"Higgs-Boson detected! Bailing out... %@", attributesDict];

[[FIRCrashlytics crashlytics] logWithFormat:@"Logging a variable argument list %@" arguments:va_list_arg];

สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับวิธีใช้ log และ logWithFormat โปรดดู เอกสารอ้างอิง ของ Crashlytics

ตั้งค่าตัวระบุผู้ใช้

ในการวินิจฉัยปัญหา การทราบว่าผู้ใช้รายใดของคุณประสบกับข้อขัดข้องดังกล่าวมักจะเป็นประโยชน์ Crashlytics มีวิธีระบุผู้ใช้โดยไม่ระบุตัวตนในรายงานข้อขัดข้องของคุณ

หากต้องการเพิ่ม ID ผู้ใช้ในรายงานของคุณ ให้กำหนดตัวระบุเฉพาะให้กับผู้ใช้แต่ละคนในรูปแบบของหมายเลข ID โทเค็น หรือค่าแฮช:

สวิฟต์

Crashlytics.crashlytics().setUserID("123456789")

วัตถุประสงค์-C

[[FIRCrashlytics crashlytics] setUserID:@"123456789"];

หากคุณจำเป็นต้องล้างตัวระบุผู้ใช้หลังจากตั้งค่าแล้ว ให้รีเซ็ตค่าเป็นสตริงว่าง การล้างตัวระบุผู้ใช้ไม่ได้เป็นการลบระเบียน Crashlytics ที่มีอยู่ หากคุณต้องการลบบันทึกที่เกี่ยวข้องกับ ID ผู้ใช้ โปรด ติดต่อฝ่ายสนับสนุนของ Firebase

รายงานข้อยกเว้นที่ไม่ร้ายแรง

นอกจากจะรายงานข้อขัดข้องของแอปโดยอัตโนมัติแล้ว Crashlytics ยังให้คุณบันทึกข้อยกเว้นที่ไม่ร้ายแรงและส่งให้คุณในครั้งต่อไปที่แอปของคุณเปิดตัว

คุณสามารถบันทึกข้อยกเว้นที่ไม่ร้ายแรงได้โดยการบันทึกวัตถุ NSError ด้วยเมธอด recordError recordError จับ call stack ของเธรดโดยการเรียก [NSThread callStackReturnAddresses]

สวิฟต์

Crashlytics.crashlytics().record(error: error)

วัตถุประสงค์-C

[[FIRCrashlytics crashlytics] recordError:error];

เมื่อใช้เมธอด recordError สิ่งสำคัญคือต้องเข้าใจโครงสร้าง NSError และวิธีที่ Crashlytics ใช้ข้อมูลเพื่อจัดกลุ่มข้อขัดข้อง การใช้เมธอด recordError อย่างไม่ถูกต้องอาจทำให้เกิดพฤติกรรมที่คาดเดาไม่ได้ และอาจทำให้ Crashlytics จำกัดการรายงานข้อผิดพลาดที่บันทึกไว้สำหรับแอปของคุณ

วัตถุ NSError มีสามอาร์กิวเมนต์:

  • domain: String
  • code: Int
  • userInfo: [AnyHashable : Any]? = nil

ซึ่งแตกต่างจากข้อขัดข้องร้ายแรงซึ่งจัดกลุ่มผ่านการวิเคราะห์การติดตามสแต็ก ข้อผิดพลาดที่บันทึกไว้จะถูกจัดกลุ่มตาม domain และ code นี่เป็นข้อแตกต่างที่สำคัญระหว่างข้อขัดข้องร้ายแรงและข้อผิดพลาดที่บันทึกไว้ ตัวอย่างเช่น:

สวิฟต์

let userInfo = [
  NSLocalizedDescriptionKey: NSLocalizedString("The request failed.", comment: ""),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString("The response returned a 404.", comment: ""),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString("Does this page exist?", comment: ""),
  "ProductID": "123456",
  "View": "MainView"
]

let error = NSError.init(domain: NSCocoaErrorDomain,
                         code: -1001,
                         userInfo: userInfo)

วัตถุประสงค์-C

NSDictionary *userInfo = @{
  NSLocalizedDescriptionKey: NSLocalizedString(@"The request failed.", nil),
  NSLocalizedFailureReasonErrorKey: NSLocalizedString(@"The response returned a 404.", nil),
  NSLocalizedRecoverySuggestionErrorKey: NSLocalizedString(@"Does this page exist?", nil),
  @"ProductID": @"123456",
  @"View": @"MainView",
};

NSError *error = [NSError errorWithDomain:NSCocoaErrorDomain
                                     code:-1001
                                 userInfo:userInfo];

เมื่อคุณบันทึกข้อผิดพลาดด้านบน ข้อผิดพลาดดังกล่าวจะสร้างปัญหาใหม่ที่จัดกลุ่มตาม NSSomeErrorDomain และ -1001 ข้อผิดพลาดที่บันทึกไว้เพิ่มเติมที่ใช้โดเมนและค่ารหัสเดียวกันจะถูกจัดกลุ่มภายใต้ปัญหาเดียวกัน ข้อมูลที่อยู่ในออบเจกต์ userInfo จะถูกแปลงเป็นคู่คีย์-ค่า และแสดงในส่วนคีย์/บันทึกภายในแต่ละปัญหา

บันทึกและคีย์ที่กำหนดเอง

เช่นเดียวกับรายงานข้อขัดข้อง คุณสามารถฝังบันทึกและคีย์ที่กำหนดเองเพื่อเพิ่มบริบทให้กับ NSError อย่างไรก็ตาม มีความแตกต่างในบันทึกที่แนบมากับการขัดข้องกับข้อผิดพลาดที่บันทึกไว้ เมื่อเกิดการหยุดทำงานและเปิดแอปใหม่อีกครั้ง บันทึกที่ Crashlytics ดึงมาจากดิสก์จะเป็นบันทึกที่เขียนขึ้นจนถึงเวลาที่เกิดการหยุดทำงาน เมื่อคุณบันทึก NSError แอปจะไม่ยุติทันที เนื่องจาก Crashlytics จะส่งรายงานข้อผิดพลาดที่บันทึกไว้ในการเปิดแอปครั้งถัดไปเท่านั้น และต้องจำกัดจำนวนพื้นที่ที่จัดสรรสำหรับบันทึกบนดิสก์ จึงเป็นไปได้ที่จะบันทึกเพียงพอหลังจากบันทึก NSError เพื่อให้บันทึกที่เกี่ยวข้องทั้งหมดถูกหมุนเวียนตามเวลาที่ Crashlytics ส่ง รายงานจากอุปกรณ์ คำนึงถึงความสมดุลนี้เมื่อบันทึก NSErrors และใช้บันทึกและคีย์ที่กำหนดเองในแอปของคุณ

การพิจารณาประสิทธิภาพ

โปรดทราบว่าการบันทึก NSError อาจมีราคาแพงพอสมควร ในขณะที่คุณทำการโทร Crashlytics จะบันทึก call stack ของเธรดปัจจุบันโดยใช้กระบวนการที่เรียกว่า stack unwinding กระบวนการนี้อาจใช้ CPU และ I/O มาก โดยเฉพาะอย่างยิ่งบนสถาปัตยกรรมที่รองรับ DWARF unwinding (arm64 และ x86) หลังจากคลายเสร็จแล้ว ข้อมูลจะถูกเขียนลงดิสก์พร้อมกัน เพื่อป้องกันข้อมูลสูญหายหากบรรทัดถัดไปขัดข้อง

แม้ว่าการเรียก API นี้บนเธรดพื้นหลังจะปลอดภัย แต่โปรดจำไว้ว่าการส่งการเรียกนี้ไปยังคิวอื่นจะสูญเสียบริบทของการติดตามสแต็กปัจจุบัน

แล้ว NSExceptions ล่ะ?

Crashlytics ไม่มีสิ่งอำนวยความสะดวกสำหรับการบันทึกและบันทึกอินสแตนซ์ NSException โดยตรง โดยทั่วไปแล้ว Cocoa และ Cocoa Touch API นั้นไม่มีข้อยกเว้น ซึ่งหมายความว่าการใช้ @catch อาจมีผลข้างเคียงที่ร้ายแรงโดยไม่ตั้งใจในกระบวนการของคุณ แม้ว่าจะใช้ด้วยความระมัดระวังอย่างยิ่งก็ตาม คุณไม่ควรใช้คำสั่ง @catch ในรหัสของคุณ โปรดดู เอกสารประกอบของ Apple ในหัวข้อ

ปรับแต่งการติดตามสแต็ก

หากแอปของคุณทำงานในสภาพแวดล้อมที่ไม่ใช่แบบเนทีฟ (เช่น C++ หรือ Unity) คุณสามารถใช้ Exception Model API เพื่อรายงานข้อมูลเมตาข้อขัดข้องในรูปแบบข้อยกเว้นแบบเนทีฟของแอป ข้อยกเว้นที่รายงานถูกทำเครื่องหมายว่าไม่ร้ายแรง

สวิฟต์

var  ex = ExceptionModel(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame(symbol:"makeError", file:"handler.js", line:495),
  StackFrame(symbol:"then", file:"routes.js", line:102),
  StackFrame(symbol:"main", file:"app.js", line:12),
]

crashlytics.record(exceptionModel:ex)

วัตถุประสงค์-C

FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithSymbol:@"makeError" file:@"handler.js" line:495],
  [FIRStackFrame stackFrameWithSymbol:@"then" file:@"routes.js" line:102],
  [FIRStackFrame stackFrameWithSymbol:@"main" file:@"app.js" line:12],
];

[[FIRCrashlytics crashlytics] recordExceptionModel:model];

เฟรมสแต็กแบบกำหนดเองสามารถเริ่มต้นได้ด้วยแอดเดรสเพียงอย่างเดียว:

สวิฟต์

var  ex = ExceptionModel.init(name:"FooException", reason:"There was a foo.")
ex.stackTrace = [
  StackFrame(address:0xfa12123),
  StackFrame(address:12412412),
  StackFrame(address:194129124),
]

crashlytics.record(exceptionModel:ex)

วัตถุประสงค์-C

FIRExceptionModel *model =
    [FIRExceptionModel exceptionModelWithName:@"FooException" reason:@"There was a foo."];
model.stackTrace = @[
  [FIRStackFrame stackFrameWithAddress:0xfa12123],
  [FIRStackFrame stackFrameWithAddress:12412412],
  [FIRStackFrame stackFrameWithAddress:194129124],
];


[[FIRCrashlytics crashlytics] recordExceptionModel:model];

เปิดใช้งานการรายงานการเลือกรับ

ตามค่าเริ่มต้น Crashlytics จะรวบรวมรายงานข้อขัดข้องสำหรับผู้ใช้แอปทั้งหมดของคุณโดยอัตโนมัติ เพื่อให้ผู้ใช้ควบคุมข้อมูลที่ส่งได้มากขึ้น คุณสามารถเปิดใช้งานการเลือกรับการรายงานโดยปิดใช้งานการรายงานอัตโนมัติ และส่งข้อมูลไปยัง Crashlytics เมื่อคุณเลือกในโค้ดของคุณเท่านั้น:

  1. ปิดการรวบรวมอัตโนมัติโดยเพิ่มคีย์ใหม่ในไฟล์ Info.plist ของคุณ:

    • คีย์: FirebaseCrashlyticsCollectionEnabled
    • ค่า: false
  2. เปิดใช้งานการรวบรวมสำหรับผู้ใช้ที่เลือกโดยเรียกใช้การแทนที่การรวบรวมข้อมูล Crashlytics ที่รันไทม์ ค่าการลบล้างจะคงอยู่ตลอดการเปิดตัวแอปของคุณ ดังนั้น Crashlytics จึงสามารถรวบรวมรายงานได้โดยอัตโนมัติ

    หากต้องการยกเลิกการรายงานข้อขัดข้องโดยอัตโนมัติ ให้ส่ง false เป็นค่าแทนที่ เมื่อตั้งค่าเป็น false ค่าใหม่จะไม่มีผลจนกว่าจะเรียกใช้แอปครั้งถัดไป

    สวิฟต์

    Crashlytics.crashlytics().setCrashlyticsCollectionEnabled(true)

    วัตถุประสงค์-C

    [[FIRCrashlytics crashlytics] setCrashlyticsCollectionEnabled:YES];

จัดการข้อมูลเชิงลึกข้อขัดข้อง

Crash Insights ช่วยคุณแก้ไขปัญหาโดยการเปรียบเทียบสแต็กเทรซที่ไม่ระบุชื่อกับการติดตามจากแอป Firebase อื่นๆ และแจ้งให้คุณทราบว่าปัญหาของคุณเป็นส่วนหนึ่งของแนวโน้มที่ใหญ่กว่าหรือไม่ สำหรับหลายๆ ปัญหา Crash Insights ยังมีแหล่งข้อมูลเพื่อช่วยคุณแก้ปัญหาข้อขัดข้อง

ข้อมูลเชิงลึกเกี่ยวกับข้อขัดข้องใช้ข้อมูลข้อขัดข้องแบบรวมเพื่อระบุแนวโน้มความเสถียรทั่วไป หากคุณไม่ต้องการแชร์ข้อมูลของแอป คุณสามารถเลือกไม่ใช้ Crash Insights ได้จากเมนู Crash Insights ที่ด้านบนของรายการปัญหา Crashlytics ใน คอนโซล Firebase