如何在Flutter应用中集成Graylog日志系统？

一、前置准备 #

• 确保Graylog服务正常运行，已配置GELF UDP/TCP输入（GELF是Graylog推荐的结构化日志格式，适配日志分析需求）
• 记录Graylog服务器地址、端口（默认GELF UDP端口为12201）及输入配置信息

二、添加依赖 #

Flutter中可直接使用gelf包实现GELF协议对接，在pubspec.yaml中添加依赖：

dependencies:
  gelf: ^2.0.0
  flutter:
    sdk: flutter

执行命令安装依赖：

flutter pub get

三、封装全局日志工具类 #

创建单例日志工具，统一处理不同级别日志的发送逻辑，便于全局调用：

import 'package:gelf/gelf.dart';
import 'package:flutter/foundation.dart';

class GraylogLogger {
  static final GraylogLogger _instance = GraylogLogger._internal();
  late GelfUdpSender _sender;

  factory GraylogLogger() => _instance;

  GraylogLogger._internal();

  /// 初始化Graylog连接
  void initialize(String host, int port, {String appName = "flutter_app"}) {
    _sender = GelfUdpSender(
      host: host,
      port: port,
      defaultFields: {
        'app_name': appName,
        'platform': defaultTargetPlatform.name,
        'app_version': '1.0.0', // 可替换为实际版本号
      },
    );
  }

  /// Debug级别日志
  void d(String message, {Map<String, dynamic>? extraFields}) {
    _sendLog(message, 'debug', extraFields);
  }

  /// Info级别日志
  void i(String message, {Map<String, dynamic>? extraFields}) {
    _sendLog(message, 'info', extraFields);
  }

  /// Warn级别日志
  void w(String message, {Map<String, dynamic>? extraFields}) {
    _sendLog(message, 'warn', extraFields);
  }

  /// Error级别日志（含异常栈）
  void e(String message, {dynamic error, StackTrace? stackTrace, Map<String, dynamic>? extraFields}) {
    final fields = extraFields ?? {};
    if (error != null) fields['error_detail'] = error.toString();
    if (stackTrace != null) fields['stack_trace'] = stackTrace.toString();
    _sendLog(message, 'error', fields);
  }

  void _sendLog(String message, String level, Map<String, dynamic>? extraFields) {
    final log = GelfMessage(
      shortMessage: message,
      level: _getLevelCode(level),
      additionalFields: extraFields,
    );
    try {
      _sender.send(log);
    } catch (e) {
      // 本地捕获发送异常，避免影响应用流程
      if (kDebugMode) print('Graylog日志发送失败: $e');
    }
  }

  // 转换Graylog日志级别编码
  int _getLevelCode(String level) {
    switch (level.toLowerCase()) {
      case 'debug':
        return 7;
      case 'info':
        return 6;
      case 'warn':
        return 4;
      case 'error':
        return 3;
      default:
        return 6;
    }
  }

  /// 关闭日志连接
  void dispose() {
    _sender.close();
  }
}

四、在应用中使用日志工具 #

在应用启动时初始化日志工具，之后在任意业务场景调用：

import 'package:flutter/material.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 替换为你的Graylog服务器地址和端口
  GraylogLogger().initialize('192.168.1.100', 12201, appName: 'my_flutter_demo');

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Graylog日志测试')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              ElevatedButton(
                onPressed: () {
                  // 发送带自定义字段的Info日志
                  GraylogLogger().i('用户进入首页', extraFields: {'user_id': 'u_1001', 'page_path': '/home'});
                },
                child: const Text('发送Info日志'),
              ),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: () {
                  // 捕获异常并发送Error日志
                  try {
                    throw Exception('测试空指针异常');
                  } catch (e, stackTrace) {
                    GraylogLogger().e('页面操作异常', error: e, stackTrace: stackTrace);
                  }
                },
                child: const Text('发送Error日志'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

五、Graylog后台验证 #

1. 登录Graylog后台，进入System > Inputs，确认GELF UDP/TCP输入处于Running状态
2. 进入Search页面，即可看到Flutter应用发送的日志，可通过app_name、level等字段过滤分析

关键注意事项 #

• 移动端需确保设备能访问Graylog服务器（本地测试需在同一局域网，生产环境需配置公网访问权限）
• 生产环境建议使用GELF TCP（可靠性更高，无丢包风险），只需将GelfUdpSender替换为GelfTcpSender
• 避免在高频调用场景发送大量日志，防止影响应用性能
• 可根据业务需求扩展日志字段（如设备型号、系统版本等），提升日志分析维度

内容的提问来源于stack exchange，提问作者Sabarinath Palani