사용자 정의 태그 사용¶

C# 및 Native C/C++ 모두 사용자 정보, SDK 전역 컨텍스트, RUM 전역 컨텍스트를 지원합니다. Log에는 별도의 전역 속성도 구성할 수 있습니다.

SDK 런타임에 추가¶

익명 사용자 식별자¶

C#과 Native C/C++는 초기화 시 로그인하지 않은 사용자를 위해 ft.rd_로 시작하는 익명 userid를 생성합니다. 식별자는 RUM 애플리케이션 ID별로 격리되며 SDK 캐시 디렉터리의 identity 하위 디렉터리에 저장됩니다. 동일한 RUM 애플리케이션 ID와 캐시 디렉터리를 사용하면 프로세스 재시작 후에도 동일한 식별자가 유지되며, C++ 호스트와 Electron Bridge도 이 동작을 그대로 따릅니다.

사용자 API를 호출하지 않으면 RUM 데이터에는 익명 userid가 사용됩니다. RUM 연동이 활성화된 Log에도 이 식별자가 포함됩니다. SetUser() 또는 guance_sdk_set_user()를 호출하면 이후 데이터에 명시적 사용자 ID가 사용됩니다. 클리어 API를 호출하면 이후 데이터는 원래의 익명 식별자를 다시 사용합니다. 해당 캐시 디렉터리를 삭제하면 식별자가 초기화됩니다.

식별자 파일에 쓸 수 없거나 잠금에 실패하면 SDK는 현재 프로세스에 임시 익명 식별자를 사용하고 C# DiagnosticListener 또는 Native 진단 출력을 통해 영속화 실패를 보고합니다. 텔레메트리 수집은 이 때문에 중단되지 않습니다.

사용자 설정¶

GuanceSdk.SetUser(
    id: "user-123",
    name: "Alice",
    email: "alice@example.com",
    extra: new Dictionary<string, object?>
    {
        ["plan"] = "enterprise"
    });

guance_sdk_set_user(
    rum,
    "user-123",
    "Alice",
    "alice@example.com");

사용자 지우기:

GuanceSdk.ClearUser();

guance_sdk_clear_user(rum);

사용자 전환은 이후 데이터에만 영향을 미치며 이미 큐에 들어간 데이터는 수정하지 않습니다.

SDK 전역 컨텍스트¶

RUM 및 연동이 활성화된 Log에 적용됩니다:

GuanceSdk.AddGlobalContext("region", "cn-east-1");
GuanceSdk.AddGlobalContext("tenant", "tenant-a");

guance_sdk_add_global_context(rum, "region", "cn-east-1");
guance_sdk_add_global_context(rum, "tenant", "tenant-a");

RUM 전역 컨텍스트¶

RUM 데이터에만 추가됩니다:

GuanceSdk.AddRumGlobalContext("ui.framework", "wpf");

guance_rum_add_rum_context(rum, "ui.framework", "win32");

Log 전역 컨텍스트¶

Log 전용 태그는 Log 초기화 시 구성합니다:

Logging = new LogConfig
{
    EnableCustomLog = true,
    GlobalContext = new Dictionary<string, object?>
    {
        ["logger_name"] = "desktop-client"
    }
}

guance_log_property context[] = {
    {"logger_name", "native-client"}
};
logging.global_context = context;
logging.global_context_count = 1;

전체 매개변수는 Log 구성을 참조하세요.

이벤트 수준 속성¶

C#의 수동 RUM 및 Log API는 이벤트 수준 사전을 지원합니다. Native Log는 guance_log_property를 허용하며, Native RUM v1의 수동 이벤트 API는 임의의 이벤트 수준 속성 구조를 제공하지 않습니다.

GuanceSdk.AddAction(
    "Save",
    "click",
    TimeSpan.FromMilliseconds(25),
    new Dictionary<string, object?>
    {
        ["result"] = "success"
    });

명명 규칙 및 예약 필드¶

• 소문자이고 안정적이며 집계 가능한 필드 이름을 사용하세요(예: feature.name).
• Token, Cookie, 비밀번호 또는 직접 식별 정보를 기록하지 마세요.
• app_id, service, env, version, sdk_name, session_id, view_id, action_id 및 플랫폼 필드는 SDK에서 관리합니다.
• 사용자 정의 컨텍스트는 SDK 예약 필드를 덮어쓸 수 없습니다.
• Native 컨텍스트 API는 문자열을 동기적으로 복사합니다. 빈 Key를 전달하지 마세요.