{"id":28456,"date":"2025-07-21T23:05:02","date_gmt":"2025-07-22T06:05:02","guid":{"rendered":"https:\/\/www.pingcap.com\/?post_type=article&#038;p=28456"},"modified":"2025-07-21T23:05:03","modified_gmt":"2025-07-22T06:05:03","slug":"monitoring-and-troubleshooting-tidb-full-text-search","status":"publish","type":"article","link":"https:\/\/www.pingcap.com\/ko\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/","title":{"rendered":"Monitoring and Troubleshooting TiDB Full-Text Search"},"content":{"rendered":"<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Introduction\"><\/span>Introduction<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p>Efficient&nbsp;<strong>Full-Text Search (FTS)<\/strong>&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS performance requires diligent monitoring and troubleshooting. Robust FTS implementations demand vigilant oversight and effective diagnostic practices. These ensure queries return timely, relevant results.<\/p>\n\n\n\n<p>However, diagnosing FTS issues in a distributed database environment can be complex without the right tools and knowledge. Fortunately, TiDB provides powerful, built-in tools and metrics for comprehensive FTS visibility. This guide helps database administrators, DevOps engineers, developers, and anyone operating TiDB clusters with FTS enabled. Learn to systematically monitor FTS performance and diagnose issues for optimal operation.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"I_Monitoring_TiDB_Full-Text_Search_Key_Tools_Metrics\"><\/span>I. Monitoring TiDB Full-Text Search: Key Tools &amp; Metrics<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">A. TiDB Dashboard: Your Central FTS Monitoring Hub<\/h3>\n\n\n\n<p>TiDB Dashboard serves as a centralized web UI for monitoring, diagnosing, and managing TiDB clusters. This includes providing detailed insights into Full-Text Search (FTS) operations. Within this dashboard, users can access FTS-specific panels that display valuable metrics essential for maintaining healthy performance.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Key FTS-Specific Dashboards\/Panels<\/h4>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>FTS Query Performance:<\/strong>\u00a0This panel provides crucial metrics like queries per second (QPS), average, P95, and P99 latencies, and error rates, enabling administrators to assess query efficiency and responsiveness.<\/li>\n\n\n\n<li><strong>FTS Indexing Performance:<\/strong>\u00a0Here, you can monitor indexing throughput, measured in documents per second, and identify indexing lag, which is the time gap between data writes and its availability for search. Additionally, details on write amplification specific to FTS processes are available.<\/li>\n\n\n\n<li><strong>Resource Utilization (FTS-related):<\/strong>\u00a0Understanding the resource demand is critical. This section displays CPU, memory, and I\/O usage for TiDB and TiKV instances, highlighting their contribution to FTS workloads.<\/li>\n\n\n\n<li><strong>Key Visualizer:<\/strong>\u00a0This tool helps identify hotspots within FTS data or index access patterns, which can be pivotal in avoiding bottlenecks.<\/li>\n<\/ol>\n\n\n\n<h3 class=\"wp-block-heading\">B. Essential FTS Metrics to Watch (Beyond Dashboard)<\/h3>\n\n\n\n<p>In addition to the TiDB Dashboard, several essential metrics warrant tracking to gauge FTS performance:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Query Success\/Failure Rates:<\/strong>\u00a0Monitoring these rates helps identify potential problems in data retrieval efficiency.<\/li>\n\n\n\n<li><strong>Index Size Growth Rate:<\/strong>\u00a0Large or rapidly growing indexes might indicate opportunities for optimization.<\/li>\n\n\n\n<li><strong>Disk Space Consumption for FTS Indexes:<\/strong>\u00a0Keeping an eye on space utilization helps prevent storage bottlenecks.<\/li>\n\n\n\n<li><strong>Network Traffic Related to FTS Components:<\/strong>\u00a0High traffic can signal inefficiencies or potential scaling needs.<\/li>\n<\/ul>\n\n\n\n<h3 class=\"wp-block-heading\">C. Setting Up Alerts<\/h3>\n\n\n\n<p>Setting up alerts in systems like Prometheus or Grafana is vital for proactively managing FTS performance. Configuring alerts for critical metrics\u2014such as high query latency, unexpected drops in indexing throughput, or FTS errors\u2014allows for prompt issue identification and resolution. Here&#8217;s a simple example of alert configuration in Prometheus:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>groups:\n- name: FTSAlerts\n  rules:\n  - alert: HighQueryLatency\n    expr: avg_over_time(query_latency{job=\"tidb\"}&#91;10m]) &gt; 0.5\n    for: 5m\n    labels:\n      severity: warning\n    annotations:\n      summary: \"High Query Latency Detected\"\n      description: \"Query latency has exceeded the acceptable threshold for the last 10 minutes.\"\n<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"II_Troubleshooting_Common_TiDB_Full-Text_Search_Issues\"><\/span>II. Troubleshooting Common TiDB Full-Text Search Issues<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">A. Slow FTS Queries<\/h3>\n\n\n\n<h4 class=\"wp-block-heading\">Diagnosis<\/h4>\n\n\n\n<p>Slow query performance can be a significant bottleneck. Use the&nbsp;<code>EXPLAIN ANALYZE<\/code>&nbsp;SQL command to view query execution plans and diagnose inefficiencies. Coupled with insights from the TiDB Dashboard, this can illustrate the latency distribution and query per second (QPS) data.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Common Causes &amp; Solutions<\/h4>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>Inefficient FTS Index:<\/strong>\u00a0Ensure the appropriate index exists for the relevant columns. Misconfigured data types and improper indexing cause significant slowdowns.<\/li>\n\n\n\n<li><strong>Suboptimal Query Syntax:<\/strong>\u00a0Enhance\u00a0<code>MATCH...AGAINST<\/code>\u00a0query efficiency by employing correct boolean operators, phrase searches, and ordering by relevance.<\/li>\n\n\n\n<li><strong>Resource Bottlenecks:<\/strong>\u00a0Scaling TiDB\/TiKV instances and adjusting resource control settings can alleviate performance congestion.<\/li>\n\n\n\n<li><strong>Data\/Index Hotspots:<\/strong>\u00a0Use the Key Visualizer to locate hotspots, adjusting data distribution with techniques like setting\u00a0<code>SHARD_ROW_ID_BITS<\/code>\u00a0or using\u00a0<code>AUTO_RANDOM<\/code>.<\/li>\n\n\n\n<li><strong>Network Latency:<\/strong>\u00a0Investigate network connectivity issues amongst cluster components, as these may cause delays.<\/li>\n<\/ol>\n\n\n\n<h3 class=\"wp-block-heading\">B. FTS Indexing Lag or Errors<\/h3>\n\n\n\n<h4 class=\"wp-block-heading\">Diagnosis<\/h4>\n\n\n\n<p>Monitor the indexing throughput and lag metrics on the TiDB Dashboard, and analyze related logs for errors in both TiDB and TiKV.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">Common Causes &amp; Solutions<\/h4>\n\n\n\n<ol class=\"wp-block-list\">\n<li><strong>High Write Workload:<\/strong>\u00a0Batched inserts or updates can reduce indexing load, while optimizing transaction sizes can streamline processes.<\/li>\n\n\n\n<li><strong>Resource Contention:<\/strong>\u00a0Ensure ample CPU, memory, and I\/O resources are available for efficient indexing.<\/li>\n\n\n\n<li><strong>Disk I\/O Bottlenecks:<\/strong>\u00a0Upgrading storage subsystems may be necessary to support increased I\/O demands.<\/li>\n\n\n\n<li><strong>Configuration Issues:<\/strong>\u00a0Verify FTS-related configuration settings for accuracy and optimization.<\/li>\n\n\n\n<li><strong>Data Integrity Issues:<\/strong>\u00a0While rare, these can lead to failures in indexing. Verification against source data is recommended.<\/li>\n<\/ol>\n\n\n\n<h3 class=\"wp-block-heading\">C. FTS Error Messages<\/h3>\n\n\n\n<p>Understanding error messages is crucial for troubleshooting. For instance, an error in the logs like&nbsp;<code>error_code: 8004<\/code>&nbsp;might indicate a capacity issue. Refer to the&nbsp;<a href=\"https:\/\/docs.pingcap.com\/\">TiDB documentation<\/a>&nbsp;for a comprehensive list of error codes and their resolutions. Examining logs in TiDB, TiKV, and PD for details will provide further guidance.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">D. Data Inconsistency (Rare)<\/h3>\n\n\n\n<p>Inconsistencies between FTS indexes and table data can be checked using commands like&nbsp;<code>ADMIN CHECK TABLE<\/code>. If inconsistencies arise, initiating specific FTS checks or contacting support for severe issues may be necessary.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"III_Proactive_Maintenance_Best_Practices\"><\/span>III. Proactive Maintenance &amp; Best Practices<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p>To maintain a robust TiDB FTS deployment, regular maintenance is essential:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Continually review FTS performance metrics and trends to preemptively address potential issues.<\/li>\n\n\n\n<li>Execute periodic FTS index health checks and rebuilds, though TiDB&#8217;s online DDL feature significantly reduces the need for this.<\/li>\n\n\n\n<li>Regularly update your TiDB cluster software to benefit from the latest FTS enhancements and bug fixes.<\/li>\n\n\n\n<li>Leverage TiDB&#8217;s diagnostic features for automated issue detection and resolution.<\/li>\n\n\n\n<li>Ensure that your TiDB configuration allocates adequate resources for FTS operations, helping to prevent bottlenecks and maintain consistent performance.<\/li>\n<\/ul>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Conclusion\"><\/span>Conclusion<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p>Effective monitoring and systematic troubleshooting are paramount for maintaining reliable and high-performing TiDB FTS deployments. By utilizing TiDB&#8217;s comprehensive array of tools and capabilities, administrators and developers can effectively manage and optimize their full-text search operations. Consistent attention to FTS-specific metrics and proactive maintenance practices will ensure that the TiDB full-text search runs seamlessly, providing users with high-quality, relevant search results, thereby enhancing their overall experience and operational efficiency.<\/p>","protected":false},"excerpt":{"rendered":"<p>Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS performance requires diligent monitoring and troubleshooting. Robust FTS implementations demand vigilant oversight and effective diagnostic practices. These ensure queries return timely, relevant results. However, diagnosing FTS issues in a distributed database environment can be complex without the right [&hellip;]<\/p>\n","protected":false},"author":305,"featured_media":0,"template":"","class_list":["post-28456","article","type-article","status-publish","hentry"],"acf":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v26.9 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Monitoring and Troubleshooting TiDB Full-Text Search | TiDB<\/title>\n<meta name=\"description\" content=\"Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS\" \/>\n<meta name=\"robots\" content=\"noindex, follow\" \/>\n<meta property=\"og:locale\" content=\"ko_KR\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Monitoring and Troubleshooting TiDB Full-Text Search | TiDB\" \/>\n<meta property=\"og:description\" content=\"Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.pingcap.com\/ko\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/\" \/>\n<meta property=\"og:site_name\" content=\"TiDB\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/facebook.com\/pingcap2015\" \/>\n<meta property=\"article:modified_time\" content=\"2025-07-22T06:05:03+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/static.pingcap.com\/files\/2024\/09\/11005522\/Homepage-Ad.png\" \/>\n\t<meta property=\"og:image:width\" content=\"1440\" \/>\n\t<meta property=\"og:image:height\" content=\"714\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:site\" content=\"@PingCAP\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"5\ubd84\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/\",\"url\":\"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/\",\"name\":\"Monitoring and Troubleshooting TiDB Full-Text Search | TiDB\",\"isPartOf\":{\"@id\":\"https:\/\/www.pingcap.com\/#website\"},\"datePublished\":\"2025-07-22T06:05:02+00:00\",\"dateModified\":\"2025-07-22T06:05:03+00:00\",\"description\":\"Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS\",\"breadcrumb\":{\"@id\":\"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/#breadcrumb\"},\"inLanguage\":\"ko-KR\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/www.pingcap.com\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Articles\",\"item\":\"https:\/\/www.pingcap.com\/article\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Monitoring and Troubleshooting TiDB Full-Text Search\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/www.pingcap.com\/#website\",\"url\":\"https:\/\/www.pingcap.com\/\",\"name\":\"TiDB\",\"description\":\"TiDB | SQL at Scale\",\"publisher\":{\"@id\":\"https:\/\/www.pingcap.com\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/www.pingcap.com\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"ko-KR\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/www.pingcap.com\/#organization\",\"name\":\"PingCAP\",\"url\":\"https:\/\/www.pingcap.com\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"ko-KR\",\"@id\":\"https:\/\/www.pingcap.com\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/static.pingcap.com\/files\/2021\/11\/pingcap-logo.png\",\"contentUrl\":\"https:\/\/static.pingcap.com\/files\/2021\/11\/pingcap-logo.png\",\"width\":811,\"height\":232,\"caption\":\"PingCAP\"},\"image\":{\"@id\":\"https:\/\/www.pingcap.com\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/facebook.com\/pingcap2015\",\"https:\/\/x.com\/PingCAP\",\"https:\/\/linkedin.com\/company\/pingcap\",\"https:\/\/youtube.com\/channel\/UCuq4puT32DzHKT5rU1IZpIA\"]}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Monitoring and Troubleshooting TiDB Full-Text Search | TiDB","description":"Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS","robots":{"index":"noindex","follow":"follow"},"og_locale":"ko_KR","og_type":"article","og_title":"Monitoring and Troubleshooting TiDB Full-Text Search | TiDB","og_description":"Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS","og_url":"https:\/\/www.pingcap.com\/ko\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/","og_site_name":"TiDB","article_publisher":"https:\/\/facebook.com\/pingcap2015","article_modified_time":"2025-07-22T06:05:03+00:00","og_image":[{"width":1440,"height":714,"url":"https:\/\/static.pingcap.com\/files\/2024\/09\/11005522\/Homepage-Ad.png","type":"image\/png"}],"twitter_card":"summary_large_image","twitter_site":"@PingCAP","twitter_misc":{"Est. reading time":"5\ubd84"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/","url":"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/","name":"Monitoring and Troubleshooting TiDB Full-Text Search | TiDB","isPartOf":{"@id":"https:\/\/www.pingcap.com\/#website"},"datePublished":"2025-07-22T06:05:02+00:00","dateModified":"2025-07-22T06:05:03+00:00","description":"Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS","breadcrumb":{"@id":"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/#breadcrumb"},"inLanguage":"ko-KR","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/www.pingcap.com\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/www.pingcap.com\/"},{"@type":"ListItem","position":2,"name":"Articles","item":"https:\/\/www.pingcap.com\/article\/"},{"@type":"ListItem","position":3,"name":"Monitoring and Troubleshooting TiDB Full-Text Search"}]},{"@type":"WebSite","@id":"https:\/\/www.pingcap.com\/#website","url":"https:\/\/www.pingcap.com\/","name":"\ud2f0DB","description":"TiDB | SQL at Scale","publisher":{"@id":"https:\/\/www.pingcap.com\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.pingcap.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"ko-KR"},{"@type":"Organization","@id":"https:\/\/www.pingcap.com\/#organization","name":"PingCAP","url":"https:\/\/www.pingcap.com\/","logo":{"@type":"ImageObject","inLanguage":"ko-KR","@id":"https:\/\/www.pingcap.com\/#\/schema\/logo\/image\/","url":"https:\/\/static.pingcap.com\/files\/2021\/11\/pingcap-logo.png","contentUrl":"https:\/\/static.pingcap.com\/files\/2021\/11\/pingcap-logo.png","width":811,"height":232,"caption":"PingCAP"},"image":{"@id":"https:\/\/www.pingcap.com\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/facebook.com\/pingcap2015","https:\/\/x.com\/PingCAP","https:\/\/linkedin.com\/company\/pingcap","https:\/\/youtube.com\/channel\/UCuq4puT32DzHKT5rU1IZpIA"]}]}},"card_markup":"        <a class=\"card-article\" href=\"https:\/\/www.pingcap.com\/ko\/article\/monitoring-and-troubleshooting-tidb-full-text-search\/\">            <h3>Monitoring and Troubleshooting TiDB Full-Text Search<\/h3>            <p>Introduction Efficient&nbsp;Full-Text Search (FTS)&nbsp;on large datasets is vital for many applications. For TiDB users, maintaining optimal FTS performance requires diligent monitoring and troubleshooting. Robust FTS implementations demand vigilant oversight and effective diagnostic practices. These ensure queries return timely, relevant results. However, diagnosing FTS issues in a distributed database environment can be complex without the right [&hellip;]<\/p>        <\/a>","_links":{"self":[{"href":"https:\/\/www.pingcap.com\/ko\/wp-json\/wp\/v2\/article\/28456","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.pingcap.com\/ko\/wp-json\/wp\/v2\/article"}],"about":[{"href":"https:\/\/www.pingcap.com\/ko\/wp-json\/wp\/v2\/types\/article"}],"author":[{"embeddable":true,"href":"https:\/\/www.pingcap.com\/ko\/wp-json\/wp\/v2\/users\/305"}],"wp:attachment":[{"href":"https:\/\/www.pingcap.com\/ko\/wp-json\/wp\/v2\/media?parent=28456"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}