이 페이지에서는 PostgreSQL용 AlloyDB에서 읽기 풀 인스턴스에 전송하는 쿼리를 조사하고 디버그하는 기술을 설명합니다.
읽기 풀의 구성 노드(IP 주소 포함)에 관한 자세한 목록을 확인합니다.
디버깅을 위해 노드에 직접 연결
AlloyDB 로그를 검사하여 읽기 풀에 전송된 쿼리를 처리하는 특정 노드를 확인합니다.
지정된 읽기 풀 노드의 모든 최근 활동에 관한 로그를 쿼리합니다.
읽기 풀 노드와 연결된 Google Cloud 측정항목을 확인합니다.
이러한 기법을 함께 사용하면 읽기 풀에 대한 진단 및 디버깅 액세스 권한을 얻을 수 있습니다. 예를 들어 클러스터의 읽기 풀 중 하나가 장기 실행 쿼리를 처리하는 동안 비정상적인 양의 CPU를 사용하는 경우 이러한 기법을 사용하면 해당 쿼리를 처리하는 노드를 확인한 다음 해당 노드에 직접 연결하여 쿼리를 추가로 검사하거나 종료할 수 있습니다.
읽기 풀 노드의 세부정보 나열
일반적인 AlloyDB 사용 시에는 읽기 풀을 구성하는 노드의 ID 또는 주소를 알 필요가 없습니다.
하지만 필요한 경우 읽기 풀 인스턴스의 노드 목록을 볼 수 있습니다. 나열된 각 노드에는 후속 진단 및 디버깅에 유용한 다음 정보가 포함됩니다.
노드의 Google Cloud ID 문자열로, 해당 노드의 최근 활동에 관한 로그 쿼리 실행에 사용됩니다.
id 필드에는 노드의 전체 ID 문자열이 포함됩니다. Google Cloud 이 문자열의 마지막 4자만 노드의 로깅된 항목에 표시됩니다.
예를 들어 이전 샘플 출력의 두 노드 중 첫 번째 노드와 관련된 로그 항목을 찾으려면 ID 문자열 hcfh를 사용하여 로그를 쿼리합니다.
노드에 직접 연결
노드의 IP 주소를 알면 PostgreSQL 서버에 직접 연결할 수 있습니다. 예를 들어 psql를 사용하여 클러스터의 VPC에 있는 VM에 연결하려면 psql 클라이언트 실행의 안내를 따르세요. 이 경우 읽기 풀 인스턴스의 IP 주소 대신 노드의 IP 주소를 제공합니다.
psql-hNODE_IP_ADDRESS-UUSERNAME
로그에서 노드 활동 찾기
AlloyDB는 읽기 풀에서 처리하는 쿼리에 관한 로그 항목에 노드 ID를 포함합니다. 일반적으로 이러한 발견된 ID는 다음 두 가지 방법으로 사용할 수 있습니다.
노드에 연결할 수 있도록 노드의 IP를 확인합니다.
추가 로그 쿼리를 실행하여 노드의 최근 활동에 관해 자세히 알아봅니다.
알려진 쿼리를 처리하는 노드 확인
특정 읽기 풀이 장기 실행 쿼리를 처리하고 있음을 알고 있다면 로그 탐색기를 사용하여 해당 쿼리를 처리하는 특정 노드의 ID를 확인할 수 있습니다.
그렇지 않고 이전 단계에 나열된 읽기 풀의 노드 중 로깅된 노드와 일치하는 ID가 없는 경우 읽기 풀이 원래 로그 항목 이후 경과한 시간 동안 해당 노드를 지원 중단한 것입니다. 이는 노드 일시성에 관한 참고사항에 설명된 대로 AlloyDB 읽기 풀의 정상적인 동작입니다. 이 경우 해당 노드에 직접 연결할 수 없습니다.
노드의 PostgreSQL 서버에 연결하면 pg_stat_activity와 같은 표준 PostgreSQL 모니터링 기법을 사용하여 노드의 현재 프로세스를 자세히 조사하고 필요에 따라 조정할 수 있습니다.
이러한 측정항목 및 기타 AlloyDB 측정항목에 관한 전체 참조 문서는 'Google Cloud metrics'의 alloydb를 참고하세요.
노드의 일시성에 관한 참고사항
일시적인 조사나 디버깅 목적으로 노드에 안전하게 연결할 수 있지만 읽기 풀을 사용하는 애플리케이션은 항상 클러스터가 인스턴스 목록에 표시하는 IP 주소를 사용하여 인스턴스 수준에서 이러한 풀에 연결해야 합니다.
AlloyDB는 읽기 풀의 노드를 교체 가능한 임시 리소스로 취급합니다. 서비스는 읽기 풀 인스턴스의 부하 분산 및 응답성을 유지하기 위해 필요한 빈도로 읽기 풀의 노드 목록을 변경합니다. 읽기 풀 인스턴스가 아닌 읽기 풀 노드에 직접 연결되는 애플리케이션은 AlloyDB가 인스턴스의 노드 목록을 업데이트할 때마다 데이터베이스 연결이 갑자기 끊길 위험이 있습니다.
항상 애플리케이션이 인스턴스 수준에서 읽기 풀에 연결되도록 하고 AlloyDB가 쿼리를 적절한 노드로 효율적으로 라우팅하도록 하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThis guide details methods for investigating and debugging queries sent to AlloyDB for PostgreSQL read pool instances, focusing on accessing and analyzing individual nodes.\u003c/p\u003e\n"],["\u003cp\u003eYou can view a detailed list of a read pool's nodes, including their Google Cloud IDs and IP addresses, which are crucial for diagnostic purposes.\u003c/p\u003e\n"],["\u003cp\u003eIt is possible to directly connect to a specific node's PostgreSQL server using its IP address for targeted debugging, but it is recommended that the main connections go to the instance level.\u003c/p\u003e\n"],["\u003cp\u003eAlloyDB logs include node IDs, enabling you to determine which node is handling a specific query and to review the node's recent activity through log queries.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Cloud metrics associated with a read pool node can be viewed through the AlloyDB System insights dashboard, offering further insight into individual node performance.\u003c/p\u003e\n"]]],[],null,["# Troubleshoot read pool queries\n\nThis page describes techniques for investigating and debugging queries\nthat AlloyDB for PostgreSQL sends to a read pool instance:\n\n- Seeing a detailed list of a read pool's constituent nodes, including their IP addresses.\n- Connecting directly to a node, for debugging purposes.\n- Examining AlloyDB logs to determine which particular node is handling any one query sent to a read pool.\n- Querying the logs for all recent activity from a given read pool node.\n- Viewing Google Cloud metrics associated with a read pool node.\n\nUsed together, these techniques give you diagnostic and debugging access\nto your read pools. For example, if one of your cluster's read pools is\nusing an unusual amount of CPU while processing a long-running query,\nthese techniques let you determine which node is handling that query,\nand then directly connect to that node to further examine or terminate\nthe query.\n| **Warning:** These techniques exist to enable temporary, diagnostic connections to read pool nodes. Always configure your applications to connect to read pool instances, rather than specific nodes. For more information, see [A note about node ephemerality](#ephemeral).\n\nList details of a read pool's nodes\n-----------------------------------\n\nIn normal AlloyDB use, you don't need to know the\nidentities or addresses of the nodes that make up your read pools.\nHowever, when necessary, you can see a list of a read pool instance's\nnodes. Each listed node includes the following information useful for\nsubsequent diagnostic and debugging:\n\n- The node's Google Cloud ID string, used for [performing log\n queries](#more-logs) about that node's recent activity.\n\n- The node's IP address within your cluster's Virtual Private Cloud\n (VPC), which you can use to [connect directly to that node's PostgreSQL\n server](#connect-directly).\n\nTo see the internal ID strings and IP addresses of a read pool's nodes,\nfollow the `gcloud`-specific instructions on [View instance\ndetails](/alloydb/docs/instance-view), but add an additional `--view=FULL`\ncommand-line argument: \n\n### gcloud\n\n gcloud alloydb instances describe \u003cvar translate=\"no\"\u003eREAD_POOL_ID\u003c/var\u003e \\\n --region=\u003cvar translate=\"no\"\u003eREGION_ID\u003c/var\u003e \\\n --cluster=\u003cvar translate=\"no\"\u003eCLUSTER_ID\u003c/var\u003e \\\n --project=\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e \\\n --view=FULL\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eREAD_POOL_ID\u003c/var\u003e: The ID of the read pool.\n- \u003cvar translate=\"no\"\u003eREGION_ID\u003c/var\u003e: The instance's region ID.\n- \u003cvar translate=\"no\"\u003eCLUSTER_ID\u003c/var\u003e: The ID of the instance's cluster.\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: The ID of the instance's project.\n\nThe output includes a section labeled `nodes`, resembling this: \n\n nodes:\n - id: \u003cvar translate=\"no\"\u003eREAD_POOL_INSTANCE_ID\u003c/var\u003e-edd4f6ed-hcfh\n ip: 10.90.80.57\n state: HEALTHY\n zoneId: us-central1-b\n - id: \u003cvar translate=\"no\"\u003eREAD_POOL_INSTANCE_ID\u003c/var\u003e-edd4f6ed-ldbm\n ip: 10.90.80.56\n state: HEALTHY\n zoneId: us-central1-c\n\nThe `id` and `ip` fields for each entry are especially relevant to the\nother techniques described on this page:\n\n- The `ip` field shows the node's IP address within the cluster's VPC.\n\n- The `id` field contains the node's full Google Cloud ID string. Only\n the final four characters of this string appear in logged entries for a\n node.\n\n For example, to find log entries involving the first of the two\n nodes in the previous sample output, [query the logs](#more-logs)\n using the ID string `hcfh`.\n\nConnect directly to a node\n--------------------------\n\nOnce you know the IP address of a node, you can connect directly to its\nPostgreSQL server. For example, to use `psql` to connect to a VM in your\ncluster's VPC, follow the instructions in [Run the psql\nclient](/alloydb/docs/connect-psql#run-psql). When you do, provide the\nnode's IP address rather than that of its read pool instance: \n\n psql -h \u003cvar translate=\"no\"\u003eNODE_IP_ADDRESS\u003c/var\u003e -U \u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e\n\nFind node activity in logs\n--------------------------\n\nAlloyDB includes node IDs in log entries about queries\nhandled by read pools. Generally speaking, you can use these discovered\nIDs in two ways:\n\n- Determine that node's IP so you can connect to it.\n- Perform further log queries to learn more about the node's recent activity.\n\n### Determine which node is handling a known query\n\nIf you know that a certain read pool is processing a long-running query,\nthen Log Explorer can help you determine the ID of the particular node\nhandling that query.\n\nNote that this technique works only on read pool instances that have\n[enabled the pgAudit extension](/alloydb/docs/pgaudit/enable-audit).\n\n1. Visit the Logs Explorer:\n\n [Go to the Logs Explorer](https://console.cloud.google.com/logs/query)\n2. In the [query\n builder](/logging/docs/view/logs-explorer-interface#query-builder), add\n `resource.labels.instance_id=\"`\u003cvar translate=\"no\"\u003eREAD_POOL_ID\u003c/var\u003e`\"` to\n the query-editor field, replacing \u003cvar translate=\"no\"\u003eREAD_POOL_ID\u003c/var\u003e with the name\n of your read pool instance.\n\n3. Add the SQL statement you're investigating, in whole or in part, to\n the query editor field. For example: `select id from MyTable`. This\n input is not case-sensitive.\n\n4. Click **Run query**.\n\n5. Use Log Explorer's controls to tune and re-run the query as needed to\n filter the results down to the most relevant ones.\n\n6. Click a log entry in the results list to expand its display.\n\n7. Click the `labels` field in the entry's expanded display.\n\n8. Note the value of `NODE_ID` under `labels`.\n\nThe result is the four-character identifier of the node handling the query.\n\n### Connect to a node mentioned in a log entry\n\nIf you want to connect directly to a particular node's PostgreSQL server\nbased on its logged activity, follow these steps:\n\n1. Note the logged node's four-character ID string. You can find this ID\n in the log entry's `NODE_ID` field.\n\n2. [List the nodes](#list-nodes) for the read pool.\n\n3. In that list, find a node with the ID string that ends wth the four\n characters you noted in the first step. It is possible that none of the\n listed nodes match.\n\n4. If you do find a matching node, use its matching IP address to\n [connect to that node's PostgreSQL server](#connect-directly).\n\n Otherwise, if none of the read pool's nodes listed in the previous\n step have IDs matching the logged node, the read pool has\n decommissioned that node in the time that has passed since the\n original log entry. This is normal behavior for\n AlloyDB read pools, as described in [A note about\n node ephermerality](#ephemeral). In this case, you can't establish\n a direct connection to that node.\n\nOnce you connect to a node's PostgreSQL server, you can\nuse standard PostgreSQL monitoring techniques, such as\n[`pg_stat_activity`](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW), to further\ninvestigate the node's current processes, and adjust them as needed.\n\n### See more log entries about a node\n\nTo see more recent logged activity about a node with a specific ID:\n\n1. Visit the Logs Explorer:\n\n [Go to the Logs Explorer](https://console.cloud.google.com/logs/query)\n2. Add `labels.NODE_ID=`\u003cvar translate=\"no\"\u003eNODE_ID\u003c/var\u003e to [the\n Logs Explorer query builder](/logging/docs/view/logs-explorer-interface#query-builder),\n replacing \u003cvar translate=\"no\"\u003eNODE_ID\u003c/var\u003e with the node's four-character\n ID string.\n\n3. Click **Run Query** to see all activity from that node within the\n selected time window, or tune the query to filter it further.\n\n4. Repeat the previous step as needed to refine your search.\n\nMonitor node metrics\n--------------------\n\n\n| **Preview**\n|\n| This product is covered by the [Pre-GA Offerings Terms](/terms/service-terms#0)\n| of the Google Cloud Terms of Service. Pre-GA products might have limited support,\n| and changes to pre-GA products might not be compatible with other pre-GA versions.\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\n\u003cbr /\u003e\n\nYou can view metrics associated with individual nodes from the\nAlloyDB System insights dashboard. For more information about\navailable node metrics, see the [System insights metrics\nreference](/alloydb/docs/reference/system-insights-metrics).\n\nTo learn which node IDs are associated with a particular read pool\ninstance, see [List details of a read pool's nodes](#list-nodes).\n\nFor full reference documentation of these and other AlloyDB\nmetrics, see [`alloydb`](/monitoring/api/metrics_gcp_a_b#gcp-alloydb) in\n\"Google Cloud metrics\".\n\nA note about node ephemerality\n------------------------------\n\nWhile you can safely connect to a node for temporary investigation or\ndebugging purposes, applications that use read pools should always\nconnect to those pools at the instance level, using the IP address that\n[its cluster displays in its instance\nlist](/alloydb/docs/cluster-list-instances).\n\nAlloyDB treats its read pools' nodes as ephemeral,\ninterchangeable resources. The service changes a read pool's roster of\nnodes as often as necessary in order to keep that read pool instance\nload-balanced and responsive. An application that connects directly to a\nread pool node, rather than to a read pool instance, runs the risk of\nabruptly disconnecting from your database whenever\nAlloyDB updates the instance's node roster.\n\nAlways let your applications connect to your read pools at the instance\nlevel, and let AlloyDB do the work of efficiently routing\nyour queries to the proper nodes.\n\nWhat's next\n-----------\n\n- Learn more about [using\n Logs Explorer](/logging/docs/view/logs-explorer-interface)."]]
