Skip to content

日志管理

SDK 提供多类独立日志能力，各类日志可 单独开启，互不影响。请按问题场景选择对应日志类型，避免在生产环境长期开启高粒度日志。各日志的特点与限制见下文对应章节。

日志类型 配置入口 典型场景
导航日志（TaLog） TaLog 导航、地图、求路、渲染等 SDK 运行问题
Search 日志 待补充 Search 检索相关问题
定位引擎日志 NavigationServiceOptions 路测定位、偏航、绑路等问题
EH 日志 EHServiceOption ADAS / EH 相关问题

1. 通用说明

  • 各类日志默认 关闭，仅在问题分析阶段按需开启，问题定位完成后及时关闭。
  • 日志目录需提前创建，并确保应用具备 读写权限。
  • 建议将日志写入应用私有目录（如 context.getExternalFilesDir(...)），避免硬编码 /sdcard/ 路径带来的权限与兼容性问题。

2. 导航日志（TaLog）

TaLog 是 SDK 统一的日志接口，输出导航、地图、求路、渲染等模块的运行信息，支持控制台输出与文件落盘。

2.1 特点与限制

  • 配置时机： 可以在调用 SDK.getInstance().initialize(...) 之前 完成配置。
  • 输出方式： 支持 Logcat 与单文件落盘；也可通过 LogHandler 自定义处理。
  • 文件划分： 不支持 按模块或 Topic 自动拆分多个日志文件；setLogPath 仅写入单个文件。需分文件时请使用 LogHandler 或应用层自行划分。

2.2 文件划分与 LogHandler

若需按业务模块划分日志（例如导航、地图、渲染分文件存储），请自行选择以下方式之一：

  1. 自行划分：在应用层根据 tag 或业务规则，将 Logcat 输出分流到不同文件。
  2. 使用 LogHandler：通过 TaLog.setLogHandler(...) 接管全部 TaLog 输出，在回调中实现自定义落盘、分文件、上传等逻辑。

设置 LogHandler 后，日志 不再 输出到 Logcat，也 不再 写入 setLogPath 指定的文件；需由 Handler 自行处理。传入 null 可移除 Handler，恢复默认输出行为。

2.3 使用场景

环境 建议级别 说明
生产环境 WARNING 或 ERROR 减少日志量，仅保留告警与错误
测试 / 路测 INFO 便于跟踪主要业务流程
专项问题分析 VERBOSE（按需） 日志量极大，仅用于短期排查；分析渲染问题时，可对渲染 Topic 单独开启 VERBOSE

2.4 开启示例

在调用 SDK.getInstance().initialize(...) 之前 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
// 启用日志输出
TaLog.enableLogs(true)

// 方式 A：写入单个文件（不支持自动分文件）
TaLog.enableWriteLogsToFile(true)
TaLog.setLogPath("<YOUR_LOG_FILE_PATH>")

// 方式 B：自定义 Handler（分文件、过滤、上传等由集成方实现）
TaLog.setLogHandler(object : LogHandler {
    override fun onLogMessage(tag: String, msg: String) {
        // 按 tag 写入不同文件，或转发至自有日志系统
    }
})

// 设置全局日志级别
TaLog.setLogLevel(NavLogLevelType.INFO)

// 仅对渲染引擎开启 VERBOSE（分析渲染问题时使用）
TaLog.setLogLevel(LogTopics.MAP_DISPLAY, NavLogLevelType.VERBOSE)

常用 API：

API 说明
TaLog.enableLogs(boolean) 是否输出到 Logcat
TaLog.enableWriteLogsToFile(boolean) 是否写入单个日志文件（无分文件能力）
TaLog.setLogPath(String) 日志文件路径（单文件）
TaLog.setLogHandler(LogHandler?) 自定义日志处理；设置后不再输出到 Logcat / 文件
TaLog.setLogLevel(int) 设置全局日志级别
TaLog.setLogLevel(String topic, int level) 为指定 Topic 单独设置级别

日志级别（NavLogLevelType）： VERBOSE < INFO < WARNING < ERROR（数值越小，输出越详细）。

常用 Topic（LogTopics）：

常量 说明
LogTopics.MAP_DISPLAY 地图渲染引擎
LogTopics.TNJNI JNI 层

Search 日志用于分析 POI 检索、Onebox 搜索、沿途搜索等 Search 相关问题。

3.1 特点与限制

Search 使用 slf4j-api 来记录日志. 使用前你需要配置相关依赖项，例如 slf4j-log4j2 或 slf4j-nop .

在 Android 系统上，建议使用 logback-android.

3.2 使用场景

  • Search 结果不符合预期
  • 搜索请求失败或超时
  • 检索排序、过滤逻辑异常

3.3 开启方式

1
runtimeOnly 'com.github.tony19:logback-android:2.0.0'

建议将 logback-android 声明为 runtimeOnly 作用域（类似于 Maven 中的 runtime 作用域）。这意味着这些类仅在运行时可用，而非在开发阶段可用。这可以确保您始终使用 Slf4j API 进行编程。

下面给出一个将 SDK 日志记录到 logcat 控制台的示例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
    <configuration>

        <!-- Create a appender to logcat -->
        <appender name="logcat" class="ch.qos.logback.classic.android.LogcatAppender">
            <encoder>
              <pattern>%msg</pattern>
            </encoder>
        </appender>

        <!-- Log from Telenav SDK -->
        <logger name="com.telenav.sdk" level="INFO">
            <appender-ref ref="logcat" />
        </logger>

        <!-- Log from Telenav Search engine -->
        <logger name="UnifiedSearch" level="INFO">
            <appender-ref ref="logcat" />
        </logger>
    </configuration>

以下示例展示了如何将 SDK 日志记录到文件 #APP_LOG_PATH#/sdkLogs/sdkLog.log 中。日志文件将每日轮换，目前仅保留最新的 7 个日志文件。更多详情请参阅 document .

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
    <configuration>
        <property name="LOG_DIR" value="#YOUR_APP_LOG DIRECTORY#" />

        <!-- Create a file appender for SDK log -->
        <appender name="sdkLog" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <filter class="ch.qos.logback.classic.filter.LevelFilter">
                <level>INFO</level>
                <onMatch>ACCEPT</onMatch>
                <onMismatch>DENY</onMismatch>
            </filter>
            <file>${LOG_DIR}/sdkLogs/sdkLog.log</file>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <!-- daily rollover -->
                <fileNamePattern>${LOG_DIR}/sdkLogs/sdkLog.log.%d{yyyy-MM-dd}</fileNamePattern>

                <!-- keep 7 days' worth of history -->
                <maxHistory>7</maxHistory>
            </rollingPolicy>
            <encoder>
                <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
            </encoder>
        </appender>

        <!-- Log from Telenav SDK -->
        <logger name="com.telenav.sdk" level="INFO">
            <appender-ref ref="sdkLog" />
        </logger>

        <!-- Log from Telenav Search engine -->
        <logger name="UnifiedSearch" level="INFO">
            <appender-ref ref="sdkLog" />
        </logger>

    </configuration>

4. 定位引擎日志

定位引擎（Position Engine）日志记录定位引擎内部运行信息，包括地图匹配、轨迹推算及 GNSS 处理等过程。

4.1 特点与限制

  • 独立性： 与 TaLog 相互独立；开启定位引擎日志不影响 TaLog 的全局级别。
  • 配置时机： 在创建 NavigationService 时，通过 NavigationServiceOptions 配置。
  • 存储方式： 支持配置独立存储目录（setPositionEngineLogStorePath）；目录须提前创建且具备读写权限。未指定路径且已开启时，默认写入 PE_Logs 子目录。

4.2 使用场景

  • 路测时分析定位漂移、偏航、绑路错误
  • 隧道、弱 GPS 场景下的位置推算问题
  • 排查 LocationProvider 输入与 SDK 内部定位结果不一致
  • 联调、问题定位阶段按需开启（生产环境建议关闭）

4.3 开启示例

在创建 NavigationService 时配置（默认关闭）：

1
2
3
4
5
6
7
8
val peLogDir = File(context.getExternalFilesDir(null), "peLog").apply { mkdirs() }

val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        .enablePositionEngineLog(true)
        .setPositionEngineLogStorePath(peLogDir.absolutePath)
        .build()
)

相关 API：

API 说明
enablePositionEngineLog(enabled) 开启 / 关闭定位引擎文件日志，默认 false
setPositionEngineLogStorePath(path) 日志存储目录，目录必须已存在

5. EH 日志（ADAS）

EH 日志记录 ADAS / Electronic Horizon 服务运行数据，用于 ADASIS 消息、路径预测等问题的分析。

5.1 特点与限制

  • 使用范围： 仅在 ADAS 相关问题排查时开启；日常导航问题请优先使用 TaLog 或定位引擎日志。
  • 独立性： 与 TaLog、定位引擎日志相互独立。
  • 配置时机： 在创建 EHService 时，通过 EHServiceOption 配置。
  • 存储方式： 支持配置独立存储目录（setLogStorePath）及日志级别（SIMPLIFIED / FULL）、压缩选项；目录须提前创建且具备读写权限。

5.2 使用场景

  • EH 消息异常、ADASIS 编码问题

5.3 开启示例

在创建 EHService 时配置（默认关闭）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
val ehLogDir = File(context.getExternalFilesDir(null), "ehLog").apply { mkdirs() }

val ehServiceOption = EHServiceOption.Builder()
    .enableLog(true)
    .setLogStorePath(ehLogDir.absolutePath)
    .setLogLevel(EHLogLevel.FULL) // 或 EHLogLevel.SIMPLIFIED
    .enableLogCompressed(false)    // 按需开启压缩
    .build()

val ehDataService = EHService.Factory.createEHDataService(ehServiceOption)

相关 API：

API 说明
enableLog(enabled) 开启 / 关闭 ADAS 日志，默认 false
setLogStorePath(path) 日志存储目录，目录必须已存在；未设置时使用配置文件中的默认路径
setLogLevel(level) 日志详细程度，默认 SIMPLIFIED
enableLogCompressed(enabled) 是否压缩日志，默认 false

日志级别（EHLogLevel）：

级别 说明
SIMPLIFIED 简化数据，仅包含几何点
FULL 完整数据

6. 建议配置组合

排查目标 建议开启
一般导航 / 播报 / 偏航 TaLog（INFO）
地图渲染异常 TaLog（INFO）+ LogTopics.MAP_DISPLAY（VERBOSE）
定位 / 绑路 TaLog（INFO）+ 定位引擎日志
ADAS / EH 消息 EH 日志（FULL）
Search 检索 Search 日志（待补充）

7. 注意事项

  • 生产版本不建议长期开启 INFO / VERBOSE 或定位引擎 / EH 文件日志，以免影响性能与存储空间。
  • VERBOSE 日志量极大，仅在问题复现阶段短期开启，定位完成后恢复为 WARNING 或 ERROR。
  • 各类日志路径请使用应用可写目录，并确保具备读写权限。
  • 问题分析结束后，关闭文件写入（TaLog.enableWriteLogsToFile(false)）或移除 LogHandler（TaLog.setLogHandler(null)），并恢复默认日志级别。