서비스 핑 개발 가이드라인

서비스 핑은 GitLab 프로세스로서 매주 GitLab에 페이로드를 수집하고 전송합니다. 페이로드는 GitLab의 사용 방법을 이해하는 데 도움이 되는 중요한 고수준 데이터를 제공합니다. 이 데이터는 다음과 같은 점에서 도움이 됩니다:

  • 서로 다른 제품 기능을 사용하는 인스턴스의 월간(또는 주간) 카운트를 비교하여 인스턴스가 어떻게 사용되는지 대략적으로 파악합니다.
  • GitLab 설치를 분류하고 이해하는 데 도움이 되는 다른 사실들을 수집합니다.
  • 우리 단계와 기능의 성공을 측정하는 데 도움이 되는 월간 활성 사용자(MAU)를 계산합니다.

서비스 핑 정보는 익명이 아닙니다. 인스턴스의 호스트 이름에 연결되지만 프로젝트 이름, 사용자 이름 또는 기타 구체적인 데이터는 포함되어 있지 않습니다.

서비스 핑은 기본적으로 활성화되어 있습니다. 그러나 자체 관리형 인스턴스에서 특정 메트릭을 비활성화할 수 있습니다. 서비스 핑이 활성화되면 GitLab은 다른 인스턴스에서 데이터를 수집하고 사용자에게 인스턴스의 사용 통계를 표시할 수 있습니다.

서비스 핑 용어

서비스 핑 구성 요소를 설명하는 데 다음 용어를 사용합니다:

  • 서비스 핑: 페이로드를 수집하고 생성하는 프로세스.
  • 서비스 데이터: 서비스 핑 JSON 페이로드의 내용입니다. 이에는 메트릭이 포함됩니다.
  • 메트릭: 주로 인스턴스의 데이터베이스 내 다른 테이블의 행 카운트로 구성됩니다. 각 메트릭은 YAML 파일의 해당 메트릭 정의와 대응됩니다.
  • MAU: 월간 활성 사용자.
  • WAU: 주간 활성 사용자.

제한 사항

  • 서비스 핑은 개별 이벤트가 아닌 메트릭만 전달합니다.
  • 버전의 서비스 핑을 전달하려면 코드베이스에서 해당 메트릭이 존재하고 instrumented 되어 있어야 합니다.

서비스 핑 요청 흐름

다음 예제는 GitLab 인스턴스, 버전 응용프로그램, 라이센스 응용프로그램, Salesforce, GitLab S3 버킷, GitLab Snowflake 데이터 웨어하우스 및 Tableau 간의 기본 요청/응답 흐름을 보여줍니다:

sequenceDiagram participant GitLab Instance participant Versions Application participant Licenses Application participant Salesforce participant S3 Bucket participant Snowflake DW participant Tableau Dashboards GitLab Instance->>Versions Application: 서비스 핑 전송 loop 사용 데이터 처리 Versions Application->>Versions Application: 사용 데이터 구문 분석 Versions Application->>Versions Application: 데이터베이스에 기록 Versions Application->>Versions Application: 라이센스 핑 시간 업데이트 end loop Salesforce용 데이터 처리 Versions Application-xLicenses Application: Zuora 구독 ID 요청 Licenses Application-xVersions Application: Zuora 구독 ID Versions Application-xSalesforce: Zuora 구독 ID로부터 Zuora 계정 ID 요청 Salesforce-xVersions Application: Zuora 계정 ID Versions Application-xSalesforce: Zuora 계정용 사용 데이터 end Versions Application->>S3 Bucket: 버전 데이터베이스 내보내기 S3 Bucket->>Snowflake DW: 데이터 가져오기 Snowflake DW->>Snowflake DW: DBT를 사용하여 데이터 변환 Snowflake DW->>Tableau Dashboards: 쿼리용 데이터 제공 Versions Application->>GitLab Instance: DevOps 점수 (대화형 개발 지수)

서비스 핑 작동 방법

  1. 서비스 핑 크론 작업은 Sidekiq에 매주 실행되도록 설정됩니다.
  2. 크론 작업이 실행되면 Gitlab::Usage::ServicePingReport.for(output: :all_metrics_values)를 호출합니다.
  3. Gitlab::Usage::ServicePingReport.for(output: :all_metrics_values)는 여러 가지 카운터 메소드 호출로 이어집니다.
  4. 모든 메소드 호출의 응답은 하나의 JSON 페이로드로 병합됩니다.
  5. 그러면 JSON 페이로드가 버전 응용프로그램에 게시됩니다. 방화벽 예외가 필요한 경우 필요한 URL은 여러 가지 사항에 따라 달라집니다. 호스트 이름이 version.gitlab.com이고 프로토콜이 TCP이며 포트 번호가 443인 경우, 필요한 URL은 https://version.gitlab.com/입니다.

  6. 오류가 발생하는 경우 다음 정보와 함께 버전 응용프로그램에보고됩니다:

    • uuid - GitLab 인스턴스 고유 식별자
    • hostname - GitLab 인스턴스 호스트 이름
    • version - GitLab 인스턴스의 현재 버전
    • elapsed - 서비스 핑 보고 프로세스 시작 후 오류가 발생한 시간 간격
    • message - 오류 메시지 
    
{
  "uuid"=>"02333324-1cd7-4c3b-a45b-a4993f05fb1d",
  "hostname"=>"127.0.0.1",
  "version"=>"14.7.0-pre",
  "elapsed"=>0.006946,
  "message"=>'PG::UndefinedColumn: ERROR:  column "non_existent_attribute" does not exist\nLINE 1: SELECT COUNT(non_existent_attribute) FROM "issues" /*applica...'
}

  7. 마지막으로 진단 목적으로 사용되는 타이밍 메타데이터 정보가 버전 응용프로그램에 제출됩니다. 이는 메트릭 식별자 목록과 메트릭 계산에 소요된 시간으로 구성됩니다: 

    {
      "metadata"=>
      {
        "uuid"=>"0000000-0000-0000-0000-000000000000",
        "metrics"=>
        [{"name"=>"version", "time_elapsed"=>1.1811964213848114e-05},
         {"name"=>"installation_type", "time_elapsed"=>0.00017242692410945892},
         {"name"=>"license_billable_users", "time_elapsed"=>0.009520471096038818},
         ....
         {"name"=>"counts.clusters_platforms_eks",
          "time_elapsed"=>0.05638605775311589},
         {"name"=>"counts.clusters_platforms_gke",
          "time_elapsed"=>0.40995341585949063},
         {"name"=>"counts.clusters_platforms_user",
          "time_elapsed"=>0.06410990096628666},
         {"name"=>"counts.clusters_management_project",
          "time_elapsed"=>0.24020783510059118}
        ]
      }
    }

Geo 보조 사이트에서

우리는 또한 Geo 보조 사이트에 특화된 메트릭을 수집하여 서비스 핑과 함께 보냅니다.

  1. Geo 보조 서비스 핑 cron 작업은 Sidekiq에서 매주 실행되도록 설정됩니다.
  2. cron 작업이 실행되면 SecondaryUsageData.update_metrics!를 호출합니다. 이는 Prometheus에서 관련된 메트릭을 수집하고 데이터를 Geo 보조 추적 데이터베이스에 저장하여 Geo 노드 상태 업데이트 중에 주 사이트로 전송합니다.

  3. Geo 노드 상태 데이터는 위에서 설명한 프로세스에서 JSON 페이로드와 함께 전송됩니다. 아래는 배열의 각 객체가 Geo 노드를 나타내는 페이로드의 예시입니다. 

    [
  {
    "git_fetch_event_count_weekly"=>nil,
    "git_push_event_count_weekly"=>nil,
    ... 기타 geo 노드 상태 필드
  }
]

서비스 핑 페이로드 예시

다음은 서비스 핑 페이로드의 예시 내용입니다. 

{
  "uuid": "0000000-0000-0000-0000-000000000000",
  "hostname": "example.com",
  "version": "12.10.0-pre",
  "installation_type": "omnibus-gitlab",
  "active_user_count": 999,
  "recorded_at": "2020-04-17T07:43:54.162+00:00",
  "edition": "EEU",
  "license_md5": "00000000000000000000000000000000",
  "license_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
  "license_id": null,
  "historical_max_users": 999,
  "licensee": {
    "Name": "ABC, Inc.",
    "Email": "email@example.com",
    "Company": "ABC, Inc."
  },
  "license_user_count": 999,
  "license_starts_at": "2020-01-01",
  "license_expires_at": "2021-01-01",
  "license_plan": "ultimate",
  "license_add_ons": {
  },
  "license_trial": false,
  "counts": {
    "assignee_lists": 999,
    "boards": 999,
    "ci_builds": 999,
    ...
  },
  "container_registry_enabled": true,
  "dependency_proxy_enabled": false,
  "gitlab_shared_runners_enabled": true,
  "gravatar_enabled": true,
  "influxdb_metrics_enabled": true,
  "ldap_enabled": false,
  "mattermost_enabled": false,
  "omniauth_enabled": true,
  "prometheus_enabled": false,
  "prometheus_metrics_enabled": false,
  "reply_by_email_enabled": "incoming+%{key}@incoming.gitlab.com",
  "signup_enabled": true,
  "projects_with_expiration_policy_disabled": 999,
  "projects_with_expiration_policy_enabled": 999,
  ...
  "elasticsearch_enabled": true,
  "license_trial_ends_on": null,
  "geo_enabled": false,
  "git": {
    "version": {
      "major": 2,
      "minor": 26,
      "patch": 1
    }
  },
  "gitaly": {
    "version": "12.10.0-rc1-93-g40980d40",
    "servers": 56,
    "clusters": 14,
    "filesystems": [
      "EXT_2_3_4"
    ]
  },
  "gitlab_pages": {
    "enabled": true,
    "version": "1.17.0"
  },
  "container_registry_server": {
    "vendor": "gitlab",
    "version": "2.9.1-gitlab",
    "db_enabled": false
  },
  "database": {
    "adapter": "postgresql",
    "version": "9.6.15",
    "pg_system_id": 6842684531675334351,
    "flavor": "Cloud SQL for PostgreSQL"
  },
  "analytics_unique_visits": {
    "g_analytics_contribution": 999,
    ...
  },
  "usage_activity_by_stage": {
    "configure": {
      "project_clusters_enabled": 999,
      ...
    },
    "create": {
      "merge_requests": 999,
      ...
    },
    "manage": {
      "events": 999,
      ...
    },
    "monitor": {
      "clusters": 999,
      ...
    },
    "package": {
      "projects_with_packages": 999
    },
    "plan": {
      "issues": 999,
      ...
    },
    "release": {
      "deployments": 999,
      ...
    },
    "secure": {
      "user_container_scanning_jobs": 999,
      ...
    },
    "verify": {
      "ci_builds": 999,
      ...
    }
  },
  "usage_activity_by_stage_monthly": {
    "configure": {
      "project_clusters_enabled": 999,
      ...
    },
    "create": {
      "merge_requests": 999,
      ...
    },
    "manage": {
      "events": 999,
      ...
    },
    "monitor": {
      "clusters": 999,
      ...
    },
    "package": {
      "projects_with_packages": 999
    },
    "plan": {
      "issues": 999,
      ...
    },
    "release": {
      "deployments": 999,
      ...
    },
    "secure": {
      "user_container_scanning_jobs": 999,
      ...
    },
    "verify": {
      "ci_builds": 999,
      ...
    }
  },
  "topology": {
    "duration_s": 0.013836685999194742,
    "application_requests_per_hour": 4224,
    "query_apdex_weekly_average": 0.996,
    "failures": [],
    "nodes": [
      {
        "node_memory_total_bytes": 33269903360,
        "node_memory_utilization": 0.35,
        "node_cpus": 16,
        "node_cpu_utilization": 0.2,
        "node_uname_info": {
          "machine": "x86_64",
          "sysname": "Linux",
          "release": "4.19.76-linuxkit"
        },
        "node_services": [
          {
            "name": "web",
            "process_count": 16,
            "process_memory_pss": 233349888,
            "process_memory_rss": 788220927,
            "process_memory_uss": 195295487,
            "server": "puma"
          },
          {
            "name": "sidekiq",
            "process_count": 1,
            "process_memory_pss": 734080000,
            "process_memory_rss": 750051328,
            "process_memory_uss": 731533312
          },
          ...
        ],
        ...
      },
      ...
    ]
  }
}

서비스 핑 데이터 내보내기

다양한 형식으로 서비스 핑 데이터를 내보내기 위한 레이크 작업이 존재합니다.

  • 레이크 작업은 count, distinct_count, sum에 대한 원시 SQL 쿼리를 내보냅니다.
  • 레이크 작업은 redis_usage_data에 대한 Redis 카운터 클래스 또는 라인을 내보냅니다.
  • 레이크 작업은 alt_usage_data 메트릭을 계산합니다.

로컬 GitLab 설치의 홈 디렉토리에서 다음과 같은 레이크 작업을 실행하여 YAML 또는 JSON 버전을 내보냅니다: 

# SQL 쿼리의 YAML 내보내기
bin/rake gitlab:usage_data:dump_sql_in_yaml

# SQL 쿼리의 JSON 내보내기
bin/rake gitlab:usage_data:dump_sql_in_json

# 비 SQL 데이터의 JSON 내보내기
bin/rake gitlab:usage_data:dump_non_sql_in_json

# 출력을 파일로 리다이렉트할 수 있습니다
bin/rake gitlab:usage_data:dump_sql_in_yaml > ~/Desktop/usage-metrics-2020-09-02.yaml

서비스 핑에 대한 폴백 값

다음 경우에 폴백 값이 반환됩니다:

상황 값
Deprecated Metric (버전 14.3에서 제거됨) -1000
타임아웃, 일반적인 실패 -1
카운터에서의 표준 오류 -2
히스토그램 메트릭실패 { ‘-1’ => -1 }

모니터링

서비스 핑 보고 프로세스 상태는 내부 SiSense 대시보드로 모니터링됩니다.

관련 주제