서비스 핑 개발 지침

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

인스턴스가 다양한 제품 기능을 어떻게 사용하는지에 대한 대략적인 감각을 얻기 위해 월별(또는 주별) 카운트를 비교합니다.
GitLab 설치를 분류하고 이해하는 데 도움이 되는 다른 사실을 수집합니다.
우리 스테이지의 성공과 기능을 측정하는 데 도움이 되는 스테이지 월간 활성 사용자(SMAU)를 계산합니다.

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

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

서비스 핑 용어

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

서비스 핑: JSON 페이로드를 수집하고 생성하는 프로세스입니다.
서비스 데이터: 서비스 핑 JSON 페이로드의 내용입니다. 여기에는 메트릭이 포함됩니다.
메트릭: 인스턴스의 데이터베이스에 있는 다양한 테이블의 행 수로 주로 구성됩니다. 각 메트릭은 YAML 파일에서 메트릭 정의와 연결됩니다.
MAU: 월간 활성 사용자입니다.
WAU: 주간 활성 사용자입니다.

한계

서비스 핑은 메트릭만 전달하며, 개별 이벤트는 전달하지 않습니다.
메트릭은 GitLab 버전에서 서비스 핑으로 전달되기 위해 코드베이스에 존재하고 계측되어야 합니다.

서비스 핑 요청 흐름

다음 예시는 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 점수 (대화형 개발 지수)

서비스 핑 작동 방식

서비스 핑 크론 작업은 Sidekiq에서 주간으로 실행되도록 설정되어 있습니다.
크론 작업이 실행되면 Gitlab::Usage::ServicePingReport.for(output: :all_metrics_values)를 호출합니다.
Gitlab::Usage::ServicePingReport.for(output: :all_metrics_values)는 ~400개 이상의 다른 카운터 메서드 호출로 전파됩니다.
모든 메서드 호출의 응답은 하나의 JSON 페이로드로 병합됩니다.
JSON 페이로드는 버전 애플리케이션에 게시됩니다.
방화벽 예외가 필요한 경우, 필요한 URL은 여러 요소에 따라 달라집니다.
호스트 이름이 version.gitlab.com인 경우, 프로토콜은 TCP이고 포트 번호는 443이며, 필요한 URL은 https://version.gitlab.com/입니다.
오류가 발생할 경우, 다음 정보와 함께 버전 애플리케이션에 보고됩니다:
- 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...'
}
```
마지막으로, 진단 목적으로 사용되는 타이밍 메타데이터 정보가 버전 애플리케이션에 제출됩니다.
여기에는 메트릭 식별자 목록과 메트릭 계산에 소요된 시간이 포함됩니다:
- GitLab 15.0에 도입됨 플래그와 함께, 기본적으로 활성화되어 있습니다.
- GitLab 15.2에서 일반적으로 사용 가능합니다. 기능 플래그 measure_service_ping_metric_collection 제거됨.

    {
      "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 보조 사이트에서

우리는 또한 Service Ping과 함께 전송하기 위해 Geo 보조 사이트에 특정한 메트릭을 수집합니다.

Geo 보조 서비스 핑 크론 작업은 Sidekiq에서 매주 실행되도록 설정되어 있습니다.
크론 작업이 실행될 때, SecondaryUsageData.update_metrics!를 호출합니다. 이는 Prometheus로부터 관련 메트릭을 수집하고 데이터를 Geo 보조 추적 데이터베이스에 저장하여 Geo 노드 상태 업데이트 시 기본 사이트로 전송합니다.
Geo 노드 상태 데이터는 위에서 설명한 프로세스에서 JSON 페이로드와 함께 전송됩니다. 다음은 배열의 각 객체가 Geo 노드를 나타내는 페이로드의 예입니다:
```
[
  {
    "git_fetch_event_count_weekly"=>nil,
    "git_push_event_count_weekly"=>nil,
    ... other geo node status fields
  }
]
```

예제 서비스 핑 페이로드

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

{
  "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
          },
          ...
        ],
        ...
      },
      ...
    ]
  }
}

서비스 핑 데이터 내보내기

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

Rake 작업은 count, distinct_count, sum에 대한 원시 SQL 쿼리를 내보냅니다.
Rake 작업은 redis_usage_data에 대한 Redis 카운터 클래스 또는 Redis 블록의 줄을 내보냅니다.
Rake 작업은 alt_usage_data 메트릭을 계산합니다.

로컬 GitLab 설치의 홈 디렉토리에서 YAML 또는 JSON 버전 중 하나에 대해 다음 Rake 작업을 실행하세요:

# 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

서비스 핑에 대한 대체 값

다음 경우에 대체 값을 반환합니다:

경우	값
사용 중단된 메트릭 (버전 14.3와 함께 제거됨)	-1000
시간 초과, 일반 오류	-1
카운터에서의 표준 오류	-2
히스토그램 메트릭 실패	{ ‘-1’ => -1 }

모니터링

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