refinery
v2.8.4
각 릴리스에 병합 된 링크 된 풀 요청의 자세한 목록은 changeLog.md를 참조하십시오. 최근 변경 사항에 대한 자세한 내용은 release_notes.md를 참조하십시오.
정유소는 꼬리 기반 샘플링 프록시이며 전체 트레이스 수준에서 작동합니다. 정유소는 전체 트레이스를 검사하고 각 흔적에 샘플링 결정을 지능적으로 적용합니다. 이러한 결정은 벌집으로 전달 된 샘플링 된 데이터에서 추적 데이터를 유지할 것인지 여부를 결정합니다.
꼬리 기반 샘플링 모델을 사용하면 한 번에 전체 트레이스를 검사하고 내용에 따라 샘플을 결정할 수 있습니다. 예를 들어, 귀하의 데이터에는 요청에 대한 HTTP 상태 코드가 포함 된 루트 범위가있을 수 있으며 캐시에서 데이터가 제공되었는지 여부에 대한 정보가 포함 된 다른 스팬. 정유소를 사용하면 500 상태 코드가 있고 캐시에서 제공되는 흔적 만 유지하도록 선택할 수 있습니다.
정유소는 여러 종류의 테일 샘플링을 지원합니다.
http.status_code 기반으로 한 키를 사용하면 샘플링 된 데이터에 포함시킬 수 있습니다.2xx 반환하는 요청에 대한 1,000 개의 흔적 중 하나4xx 반환하는 요청에 대한 10 가지 흔적 중 하나5xx 반환하는 모든 요청정유소를 사용하면 위의 모든 기술을 결합하여 원하는 샘플링 동작을 달성 할 수 있습니다.
정유소는 모든 흔적에 도달 할 수있는 인프라 내에 앉도록 설계되었습니다. 정유소는 독립형 실행 또는 별도의로드 밸런서를 통해 액세스 할 수있는 두 개 이상의 정유 공정 프로세스 클러스터에 배치 될 수 있습니다.
정유소 프로세스는 단일 서버의 흔적을 집중시키기 위해 서로 통신 할 수 있어야합니다.
애플리케이션 (또는 기타 벌집 이벤트 소스) 내에서 API Host http(s)://load-balancer/ 로 구성됩니다. API 키, 데이터 세트 이름 등과 같이 다른 모든 것은 동일하게 유지됩니다.
모든 정유소 인스턴스는 다음과 같습니다.
linux/amd64 또는 linux/arm64 운영 체제대부분의 경우 정유소에는 하나의 노드 만 있으면됩니다. 많은 양의 트래픽이 발생하는 경우 여러 노드로 확장해야하며 스케일링을 처리하려면 작은 Redis 인스턴스가 필요할 수 있습니다.
초기 설정 후 RAM의 양과 코어 수를 늘리는 것이 좋습니다. 구성 값을 증가시켜 추가 RAM 및 CPU를 사용할 수 있습니다. 특히, CacheCapacity 는 중요한 구성 값입니다. 정유소의 Stress Relief 시스템은 정유소가 얼마나 열심히 작동하는지, 호출시 ( reason 에 따라) 스트레스를 줄이기 위해 증가 해야하는 정유소 구성 값의 이름을 기록합니다. 스케일링 및 문제 해결 문서를 사용하여 자세한 내용을 알아보십시오.
정유소는 Honeycomb Helm 저장소에서 헬름 차트로 제공됩니다.
기본값 파일을 사용하는 다음 명령으로 정유소를 설치할 수 있습니다.
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refinery또는 자신의 사용자 정의 값 파일을 제공하십시오.
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml 여기서 /path/to/refinery-values.yaml 파일의 경로입니다.
클러스터에서 작동 할 때 정유 공장은 모든 스팬을 추적으로 단일 인스턴스로 수집하여 추적 결정을 내릴 수 있도록 기대합니다. 각 스팬이 독립적으로 도착하므로 각 정유소 인스턴스는 모든 동료와 통신하여 추적을 올바른 인스턴스에 배포 할 수 있어야합니다.
이 커뮤니케이션은 구성 파일의 명백한 동료 목록을 통해 또는 공유 된 Redis 캐시를 통해 자체 등록을 사용하여 두 가지 방식으로 관리 할 수 있습니다. 설치는 일반적으로 Redis를 사용하는 것을 선호해야합니다. 대규모 설치에서도 Redis 서버의로드는 상당히 가볍고 각 인스턴스는 분당 몇 가지 요청 만합니다. 분수 CPU를 갖는 단일 Redis 인스턴스로는 일반적으로 충분합니다.
구성은 정유 공장의 두 구성 파일로 제어되는데,이 파일은 일반적으로 일반 구성을위한 config.yaml 및 샘플링 구성을위한 rules.yaml 위한 config.yaml이라고합니다. 이 파일은 액세스 가능한 파일 시스템에서로드하거나 URL에서 무단 GET 요청을로드 할 수 있습니다.
config.yaml 및 정유소 구성 문서에서 정유소 작업을 제어하는 모든 매개 변수에 대해 자세히 알아보십시오.
정유소 샘플링 방법 문서에서 rules.yaml 에 대해 자세히 알아보십시오.
둘 이상의 구성 소스를 지정하는 것이 유효합니다. 예를 들어, 공통 구성 파일과 키 만 포함 된 별도의 파일을 가질 수 있습니다. 명령 줄에서 명령 줄 스위치를 반복하여 여러 파일을 지정하십시오. 환경 변수에서 쉼표로 여러 구성 위치를 별도로 분리하십시오.
정유소는 일반적인 Linux 스타일 명령 줄 응용 프로그램이며 여러 명령 줄 스위치를 지원합니다.
refinery -h 모든 명령 줄 옵션 및 지원되는 환경 변수를 나열하는 확장 된 도움말 텍스트를 인쇄합니다.
정유소는 다음과 같은 주요 환경 변수를 지원합니다. 전체 목록은 명령 줄 도움말 또는 온라인 문서를 참조하십시오. 명령 줄 스위치는 파일 구성보다 우선하며 환경 변수는 두 가지보다 우선합니다.
| 환경 변수 | 구성 필드 |
|---|---|
REFINERY_GRPC_LISTEN_ADDRESS | GRPCListenAddr |
REFINERY_REDIS_HOST | PeerManagement.RedisHost |
REFINERY_REDIS_USERNAME | PeerManagement.RedisUsername |
REFINERY_REDIS_PASSWORD | PeerManagement.RedisPassword |
REFINERY_HONEYCOMB_API_KEY | HoneycombLogger.LoggerAPIKey |
REFINERY_HONEYCOMB_METRICS_API_KEY | LegacyMetrics.APIKey |
REFINERY_HONEYCOMB_API_KEY | LegacyMetrics.APIKey |
REFINERY_QUERY_AUTH_TOKEN | QueryAuthToken |
참고 : REFINERY_HONEYCOMB_METRICS_API_KEY LegacyMetrics.APIKey 구성에 대해 REFINERY_HONEYCOMB_API_KEY 보다 우선합니다.
Honeycomb에 데이터를 보내려면 API 키를 원격 측정에 연결해야합니다. 원격 측정 관리를보다 쉽게 관리하기 위해 정유소는 AcceptOnlyListedKeys 및 SendKeyMode 와 함께 ReceiveKeys 및 SendKey 구성 옵션을 지원합니다. 다양한 조합에서는 많은 표현력이 있습니다. 이 매개 변수를 설정하는 방법에 대한 자세한 내용은 구성 문서를 참조하십시오.
특정 시나리오에 대한 빠른 시작은 다음과 같습니다.
SendKey 설정하십시오SendKeyMode all 에게 설정하십시오SendKey 설정하십시오SendKeyMode nonblank 로 설정하십시오ReceiveKeys 설정하십시오SendKey 설정하십시오SendKeyMode unlisted 으로 설정하십시오SendKey 설정하십시오SendKeyMode missingonly 로 설정하십시오ReceiveKeys 에 추가하십시오AcceptOnlyListedKeys true 로 설정하십시오SendKey 설정하십시오SendKeyMode listedonly 로 설정하십시오AcceptOnlyListedKeys false 으로 설정하십시오ReceiveKeys 설정하십시오SendKey 설정하십시오SendKeyMode listedonly 로 설정하십시오 + note + + 클래식 API 키와 함께 베어 라인을 사용하여 정유소로 데이터를 보낼 때 SendKey 가 환경 및 서비스 (E & S) 키가 아닌 고전적인 키 임금을 확인하십시오.
정유소를 시작하거나 샘플링 규칙을 업데이트 할 때 트래픽 삭제를 시작하기 전에 규칙이 예상대로 작동하는지 확인하는 것이 도움이 될 수 있습니다. 그렇게하려면 정유소에서 드라이 런 모드를 사용하십시오.
구성 파일 ( config.yaml )에서 DryRun = true 추가하여 드라이 런 모드를 활성화합니다. 그런 다음 Honeycomb UI의 쿼리 빌더를 사용하여 쿼리를 실행하여 결과를 확인하고 규칙이 의도 한대로 작동하는지 확인하십시오.
드라이 런 모드가 활성화되면 메트릭 trace_send_kept 가 각 트레이스에 대해 증가하고 trace_send_dropped 의 메트릭은 모든 트레이스를 벌집으로 보내는 것을 반영하여 0 으로 유지됩니다.
정유소는 제한된 대기열과 원형 버퍼를 사용하여 할당 트레이스를 관리하므로 대량의 메모리 사용하더라도 극적으로 확장되지 않아야합니다. 그러나 추적이 원형 버퍼에 저장되면 추적의 처리량이 버퍼의 크기를 초과 할 때 상황이 잘못되기 시작합니다. 통계가 구성된 경우 collect_cache_buffer_overrun 이라는 카운터가 발생할 때마다 증가합니다. 이것의 증상은 흔적이 함께 축적되는 것을 멈출 것이며, 대신 같은 트레이스의 일부가되어야하는 스팬은 두 개의 별도 흔적으로 취급됩니다. 모든 흔적은 계속해서 전송되고 샘플링되지만 일부 샘플링 결정은 불완전한 데이터에서 이루어집니다. 원형 버퍼의 크기는 CacheCapacity 라는 구성 옵션입니다. 좋은 값을 선택하려면 트레이스의 처리량 (예 : 트레이스 / 두 번째 시작)을 고려하고 트레이스의 최대 지속 시간 (예 : 3 초)을 곱한 다음 큰 버퍼 (아마도 10x)를 곱해야합니다. . 이 추정치는 좋은 헤드 룸을 제공 할 것입니다.
클러스터에 필요한 기계의 수를 결정하는 것은 정확한 과학이 아니며 버퍼 오버런을 지켜 보는 데 큰 영향을 미칩니다. 그러나 거친 휴리스틱의 경우 약 2GB의 메모리를 사용하여 5,000 개의 들어오는 이벤트를 처리하고 초당 500 개의 하위 초 트레이스를 추적하기 위해 단일 기계를 계산합니다 (각각의 전체 트레이스는 1 초 미만 및 평균 크기의 추적 당 평균 크기의 추적). .
정유소는 Stress Relief 라는 메커니즘을 제공하여 무거운 하중에서 안정성을 향상시킵니다. stress_level 메트릭은 큐 크기 및 메모리 사용과 관련된 여러 정제소 메트릭으로 구성된 0에서 100 사이의 척도의 합성 메트릭입니다. 정상 작동 하에서 그 값은 일반적으로 단일 자릿수에 있어야합니다. 트래픽이 높은 버스트 중에는 스트레스 수준이 높아져 볼륨이 떨어질 때 다시 떨어질 수 있습니다. 100에 접근함에 따라 정유소가 실패하고 충돌하기 시작할 가능성이 점점 더 많습니다.
Stress Relief 스트레스가 안정성에 위험 해지면 stress_level 메트릭과 흘림 하중을 모니터링 할 수있는 시스템입니다. ActivationLevel 에 도달하면 Stress Relief 모드가 활성화됩니다. 이 상태에서. 정유소는 나머지 트레이스를 저장하거나 규칙 조건을 평가하지 않고도 TraceID 에 따라 각 스팬을 결정적으로 샘플링합니다. Stress Relief 응력이 구성에 지정된 DeactivationLevel 아래로 떨어질 때까지 활성 상태로 유지됩니다.
스트레스 릴리프 설정은 다음과 같습니다.
Mode - Stress Relief 사용 방법을 나타내는 설정. Stress Relief 활성화되지 않음을 나타내지 never . monitor ActivationLevel 속도가 활성화되고 도달 할 때 비활성화 할 때 Stress Relief 활성화되는 것을 의미합니다. always Stress Relief 모드가 지속적으로 참여할 것임을 의미합니다. always 모드는 비상 상황에서 사용하기위한 것입니다.ActivationLevel 응력 수준 이이 임계 값보다 높아지면 정유소는 Stress Relief 활성화합니다.DeactivationLevel 응력 수준 이이 임계 값 아래로 떨어지면 정유소는 Stress Relief 비활성화합니다.SamplingRate Stress Relief 활성화되는 동안 정유소 샘플이있는 속도. stress_level 은 현재 정유소의 전체 부하에 가장 적합한 프록시입니다. Stress Relief 활성화되지 않더라도 stress_level 이 자주 50 이상인 경우 정유소에 더 많은 CPU, 더 많은 메모리 또는 더 많은 노드가 필요하다는 좋은 지표입니다. 반면에, stress_level 두 자리로 들어 가지 않으면 정유소가 과도하게 제공 될 가능성이 높습니다.
정유소는 많은 메트릭을 방출하여 프로세스의 건강에 대한 정보를 제공합니다. 이 메트릭은 일반적으로 개방형 원격 측정법을 사용하여 벌집으로 보내야하며 프로 메테우스에도 노출 될 수도 있습니다. 볼 흥미로운 것은 다음과 같습니다.
[incoming|peer]_router_* : 얼마나 많은 이벤트 (추적 정보 없음)와 스팬 (추적 정보가 있음)이 수락되었으며 동료에게 보낸 사람은 몇 명입니까?collect_cache_buffer_overrun : 이것은 0으로 남아 있어야합니다. 양수 값은 정유소의 원형 트레이스 버퍼의 크기를 늘려야한다는 것을 나타냅니다 (구성 CacheCapacity 통해).process_uptime_seconds : 각 프로세스의 가동 시간을 기록합니다. 예기치 않은 재시작을 메모리 제약의 키로 찾으십시오. 기본 로깅 수준은 상당히 warn 합니다. debug 수준은 생산에 사용하기에는 너무 많은 데이터를 방출하지만 추적 결정 정보를 포함하여 사전 생산 환경에서 우수한 정보를 포함합니다. info 그 사이에 있습니다. 초기 구성 중에 로깅 레벨을 debug 로 설정하면 작동중인 내용과 그렇지 않은 것이 이해하는 데 도움이되지만 트래픽 볼륨이 증가하면 warn 또는 error 로 설정해야합니다. 로그는 stdout 또는 꿀벌로 전송 될 수 있습니다.
정유소는 시작 또는 구성이 다시로드 된 경우 구성을 확인하고 모든 문제에 대한 진단을 방출합니다. 스타트 업에서는 시작을 거부합니다. Reload에서는 기존 구성이 변경되지 않습니다.
정유소 호스트에 액세스 할 수있는 서버의 명령 줄에서 /query 엔드 포인트 중 하나를 사용하여로드 된 구성을 확인하십시오.
/query 엔드 포인트는 구성 파일에 QueryAuthToken 지정하거나 환경에서 REFINERY_QUERY_AUTH_TOKEN 지정하여 보호되며 활성화 될 수 있습니다. 모든 /query 엔드 포인트에 대한 모든 요청에는 지정된 토큰의 값으로 설정된 헤더 X-Honeycomb-Refinery-Query 포함되어야합니다.
파일 기반 구성 (현재 지원되는 유일한 유형)의 경우 hash 값은 주어진 구성 파일의 md5sum 명령에 의해 생성 된 값과 동일합니다.
이 모든 명령에 대해 :
$REFINERY_HOST 정유소의 URL이어야합니다.$FORMAT yaml , toml 또는 json 중 하나 일 수 있습니다.$DATASET 확인하려는 데이터 세트의 이름입니다.전체 규칙 구성을 검색하려면 :
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
정유소가 지정된 데이터 세트에 사용하는 규칙 세트를 검색하려면 규칙 세트에 샘플러 유형의 맵으로 반환됩니다.
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
구성이 마지막으로로드 된 타임 스탬프를 포함하여 현재 사용중인 구성에 대한 정보를 검색하려면 다음과 같습니다.
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
정유소는 샘플링 결정을 디버깅하는 데 도움이되는 정보가 포함 된 원격 측정을 보낼 수 있습니다. 구성 파일에서 AddRuleReasonToTrace true 로 설정하십시오. 이로 인해 Honeycomb로 전송되는 흔적이 발생하여 Field meta.refinery.reason 포함하여 트레이스가 포함 된 규칙을 평가 한 텍스트가 포함됩니다.
정유소는 아직 추적을 버퍼하거나 디스크에 대한 샘플링 결정을하지 않습니다. 프로세스를 다시 시작하면 모든 기내 트레이스가 플러시되지만 (상류로 꿀벌로 전송) 과거의 추적 결정의 기록을 잃게됩니다. 다시 시작하면 깨끗한 슬레이트로 시작됩니다.
각 디렉토리 내에서 종속성 내보내기는 디렉토리와 동일한 이름을 가진 파일에 있고 (대부분) 다른 파일은 해당 인터페이스의 대체 구현입니다. 예를 들어 logger 에서 /logger/logger.go 인터페이스 정의가 포함되어 있으며 logger/honeycomb.go 에는 로그를 벌집으로 보내는 logger 인터페이스의 구현이 포함되어 있습니다.
main.go 앱을 설정하고 사용할 의존성 구현 버전 (예 : 어떤 Logger, What Sampler 등) 모든 것을 시작한 다음 App 시작합니다.
app/app.go 주요 제어 지점입니다. Start 기능이 종료되면 프로그램이 종료됩니다. 들어오는 이벤트를 듣는 두 개의 Router 를 시작합니다.
route/route.go 들어오는 트래픽을 위해 네트워크에서 리스팅됩니다. 두 개의 라우터가 실행되며 다른 유형의 트래픽을 처리합니다. 외부 세계에서 나오는 이벤트 ( incoming 라우터) 및 정유소 클러스터 ( peer 트래픽)의 다른 멤버에서 나오는 이벤트. 이벤트가 나면 다음에 어디로 가야하는지 결정합니다.이 수신 요청 이벤트 (또는 이벤트 배치)입니까? 그렇다면 추적 ID가 있습니까? 이벤트가 아닌 모든 것은 트레이스 ID가없는 이벤트가 즉시 벌집으로 전달되도록 transmission 에 건네집니다. 추적 ID가있는 이벤트 인 경우 라우터는 트레이스 ID를 추출한 다음 sharder 를 사용하여 정유소 클러스터의 어떤 구성원 이이 트레이스를 처리 해야하는지 결정합니다. 동료 인 경우 이벤트는 그 동료에게 전달됩니다. 그것이 우리라면, 이벤트는 내부 표현으로 변형되어 collector 에게 스팬을 흔적으로 묶기 위해 전달됩니다.
collect/collect.go 고집가는 스팬을 트레이스로 묶고 허니컴으로 보내야하는지 또는 떨어 뜨려야하는지 결정해야합니다. 추적 ID가 처음 보이면 수집기가 타이머를 시작합니다. 트레이스 ID가 있고 상위 ID가없는 루트 범위가 타이머가 만료되기 전에 도착하면 추적이 완전한 것으로 간주됩니다. 트레이스가 전송되고 타이머가 취소됩니다. 루트 범위가 도착하기 전에 타이머가 만료되면, 트레이스가 완료되었는지 여부에 관계없이 추적이 전송됩니다. 전송 직전에 컬렉터는 sampler 에게 샘플 속도와 추적을 유지 해야하는지 여부를 요청합니다. 수집가는이 샘플링 결정에 순종하고이를 기록합니다 (기록은 결정이 내린 후 추적의 일부로 들어올 수있는 모든 범위에 적용됩니다). 샘플링 결정을 내린 후, 흔적을 유지하려면 실제 전송을 위해 transmission 으로 전달됩니다.
transmit/transmit.go HTTP 상호 작용을 중심으로 래퍼입니다. 배치 이벤트를 함께 처리하고 상류로 보냅니다.
logger 와 metrics 정유소 자체가 생산하는 로그 및 메트릭을 관리하기위한 것입니다.
sampler 에는 제공된 트레이스에 따라 샘플 속도를 계산하는 알고리즘이 포함되어 있습니다.
sharder 클러스터 정유소 구성의 어떤 피어가 개별 추적을 처리 해야하는지 결정합니다.
types 패키지간에 데이터를 핸드링하는 데 사용되는 몇 가지 유형 정의가 포함되어 있습니다.
