Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/128622/?format=api
{ "id": 128622, "url": "http://patches.dpdk.org/api/patches/128622/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20230613143355.77914-3-bruce.richardson@intel.com/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20230613143355.77914-3-bruce.richardson@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20230613143355.77914-3-bruce.richardson@intel.com", "date": "2023-06-13T14:33:55", "name": "[2/2] doc/contributing: guidelines for logging, tracing and telemetry", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "20f3aacd936a6ee33d3bdfef8ba25f1250022822", "submitter": { "id": 20, "url": "http://patches.dpdk.org/api/people/20/?format=api", "name": "Bruce Richardson", "email": "bruce.richardson@intel.com" }, "delegate": { "id": 1, "url": "http://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20230613143355.77914-3-bruce.richardson@intel.com/mbox/", "series": [ { "id": 28486, "url": "http://patches.dpdk.org/api/series/28486/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=28486", "date": "2023-06-13T14:33:53", "name": "Improve docs on getting info on running process", "version": 1, "mbox": "http://patches.dpdk.org/series/28486/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/128622/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/128622/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 8087842CAB;\n\tTue, 13 Jun 2023 16:34:27 +0200 (CEST)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 4DCCC42BAC;\n\tTue, 13 Jun 2023 16:34:23 +0200 (CEST)", "from mga18.intel.com (mga18.intel.com [134.134.136.126])\n by mails.dpdk.org (Postfix) with ESMTP id B4F0440A8A\n for <dev@dpdk.org>; Tue, 13 Jun 2023 16:34:20 +0200 (CEST)", "from fmsmga005.fm.intel.com ([10.253.24.32])\n by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 13 Jun 2023 07:34:19 -0700", "from silpixa00401385.ir.intel.com ([10.237.214.11])\n by fmsmga005.fm.intel.com with ESMTP; 13 Jun 2023 07:34:18 -0700" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple;\n d=intel.com; i=@intel.com; q=dns/txt; s=Intel;\n t=1686666860; x=1718202860;\n h=from:to:cc:subject:date:message-id:in-reply-to:\n references:mime-version:content-transfer-encoding;\n bh=sCfvjlpwLWHxy0YdjLiyg+mSO86NrATV5JUQXmNPqzA=;\n b=NISMCiOvFXvwf1l1/KaJAryZGtWu6S4UVDR09gwsjY0AHCAlRWXsdcb/\n e/ywcGl8PyQ+vgKEypwabNVB35AqWIV1PUPUT5puGCh5D1O0cDDtM7WME\n XGnz5/clGZFZqA1Xu4jYBoHg3n4RIX+JZBsidhhCtEa1zHcC8YwFfyXHn\n 7seV0q5wkX7t8bRUTdljsN2li54HMPsGDx5MWdEELee0HJj7f3RrMjyAT\n LCN6VpY92WSJXfzKcsDgXgVM0gmJl9OFv5HpxFCtPQTaRlpg75x2zpvar\n tS18SgcyhuSaekCTXXIiXH4DMeN1lm8C6saSDE5pH650cuY6oziB4m06o A==;", "X-IronPort-AV": [ "E=McAfee;i=\"6600,9927,10740\"; a=\"343039786\"", "E=Sophos;i=\"6.00,239,1681196400\"; d=\"scan'208\";a=\"343039786\"", "E=McAfee;i=\"6600,9927,10740\"; a=\"1041787645\"", "E=Sophos;i=\"6.00,239,1681196400\"; d=\"scan'208\";a=\"1041787645\"" ], "X-ExtLoop1": "1", "From": "Bruce Richardson <bruce.richardson@intel.com>", "To": "dev@dpdk.org", "Cc": "Bruce Richardson <bruce.richardson@intel.com>", "Subject": "[PATCH 2/2] doc/contributing: guidelines for logging,\n tracing and telemetry", "Date": "Tue, 13 Jun 2023 15:33:55 +0100", "Message-Id": "<20230613143355.77914-3-bruce.richardson@intel.com>", "X-Mailer": "git-send-email 2.39.2", "In-Reply-To": "<20230613143355.77914-1-bruce.richardson@intel.com>", "References": "<20230613143355.77914-1-bruce.richardson@intel.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org" }, "content": "As discussed by DPDK technical board [1], out contributor guide should\ninclude some details as to when to use logging vs tracing vs telemetry\nto provide the end user with information about the running process and\nthe DPDK libraries it uses.\n\n[1] https://mails.dpdk.org/archives/dev/2023-March/265204.html\n\nSigned-off-by: Bruce Richardson <bruce.richardson@intel.com>\n---\n doc/guides/contributing/coding_style.rst | 2 ++\n doc/guides/contributing/design.rst | 34 ++++++++++++++++++++++++\n doc/guides/prog_guide/telemetry_lib.rst | 2 ++\n doc/guides/prog_guide/trace_lib.rst | 2 ++\n 4 files changed, 40 insertions(+)", "diff": "diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst\nindex f50a78a346..13b2390d9e 100644\n--- a/doc/guides/contributing/coding_style.rst\n+++ b/doc/guides/contributing/coding_style.rst\n@@ -794,6 +794,8 @@ Control Statements\n /* NOTREACHED */\n }\n \n+.. _dynamic_logging:\n+\n Dynamic Logging\n ---------------\n \ndiff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst\nindex d24a7ff6a0..9edf3ea43b 100644\n--- a/doc/guides/contributing/design.rst\n+++ b/doc/guides/contributing/design.rst\n@@ -4,6 +4,40 @@\n Design\n ======\n \n+Runtime Information - Logging, Tracing and Telemetry\n+-------------------------------------------------------\n+\n+It is often desirable to provide information to the end-user as to what is happening to the application at runtime.\n+DPDK provides a number of built-in mechanisms to provide this introspection:\n+\n+* :ref:`Logging<dynamic_logging>`\n+* :ref:`Tracing<trace_library>`\n+* :ref:`Telemetry<telemetry_library>`\n+\n+Each of these has it's own strengths and suitabilities for use within DPDK components.\n+\n+Below are some guidelines for when each should be used:\n+\n+* For reporting error conditions, or other abnormal runtime issues, *logging* should be used.\n+ Depending on the severity of the issue, the appropriate log level, for example,\n+ ``ERROR``, ``WARNING`` or ``NOTICE``, should be used.\n+* In general, it is not recommended that the DPDK logging functions should be used for debugging.\n+ Although the ``DEBUG`` log level may be used in components, it should only be used sparingly,\n+ and the *tracing* functionality used instead.\n+ More specifically:\n+\n+ * for cases where a path through the code is only likely to be taken once,\n+ for example, initialization code, either *logging* at ``DEBUG`` level or *tracing* may be used -\n+ though tracing is preferred.\n+ * where a path is to be taken multiple times within a short timeframe, for example,\n+ datapath or regular control plane code, *tracing* should be used.\n+\n+* For numerical or statistical data generated by a component, for example, per-packet statistics,\n+ *telemetry* should be used.\n+* For any data where the data may need to be gathered at any point in the execution to help assess the state of the application component,\n+ for example, core configuration, device information, *telemetry* should be used.\n+\n+\n Environment or Architecture-specific Sources\n --------------------------------------------\n \ndiff --git a/doc/guides/prog_guide/telemetry_lib.rst b/doc/guides/prog_guide/telemetry_lib.rst\nindex 32f525a67f..71f8bd735e 100644\n--- a/doc/guides/prog_guide/telemetry_lib.rst\n+++ b/doc/guides/prog_guide/telemetry_lib.rst\n@@ -1,6 +1,8 @@\n .. SPDX-License-Identifier: BSD-3-Clause\n Copyright(c) 2020 Intel Corporation.\n \n+.. _telemetry_library:\n+\n Telemetry Library\n =================\n \ndiff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/trace_lib.rst\nindex e5718feddc..a3b8a7c2eb 100644\n--- a/doc/guides/prog_guide/trace_lib.rst\n+++ b/doc/guides/prog_guide/trace_lib.rst\n@@ -1,6 +1,8 @@\n .. SPDX-License-Identifier: BSD-3-Clause\n Copyright(C) 2020 Marvell International Ltd.\n \n+.. _trace_library:\n+\n Trace Library\n =============\n \n", "prefixes": [ "2/2" ] }