From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id D940CA0526; Wed, 22 Jul 2020 19:27:26 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 5EE891BFCA; Wed, 22 Jul 2020 19:27:25 +0200 (CEST) Received: from out5-smtp.messagingengine.com (out5-smtp.messagingengine.com [66.111.4.29]) by dpdk.org (Postfix) with ESMTP id DE6DC1BFBB for ; Wed, 22 Jul 2020 19:27:23 +0200 (CEST) Received: from compute7.internal (compute7.nyi.internal [10.202.2.47]) by mailout.nyi.internal (Postfix) with ESMTP id 442BB5C00FD; Wed, 22 Jul 2020 13:27:21 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute7.internal (MEProxy); Wed, 22 Jul 2020 13:27:21 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=fm1; bh= zflnof/39JaLf6PZqZ+eYraAgEjxC8tE7aJt/XV0v6w=; b=gF8HnL2M10zdHdhR KVnk6VB6EV++IDMfKbQHcS1KWkpr1Bt/OUWx+wTuJ+Y2xxT4WbIUhta5qDVP8gWU ZknRNCvefvCPHot2wpMDTTqB3AtGyU3sUZlJ5y1JR+InXlsXKHFj+UovM9gTw7DJ eyF054kTCNBLuXJQrh/BN4x2KhGiVPPKPV3oSI4ZvxSrZL4ofWpkXgUQLn2d8DWe VJi/8GQx1hKqBhNu6cxhfW2NotvLKNSAlWDKcy4iB5h+3CZ5yh6bTCZwKy7V3EEE 6Ylp4RkMk4L46jyPsgPNP9tsE6xI56Gbjrnzuo+6jz9oHGuvkdctvVsYpwxWllA6 ndaAAQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=zflnof/39JaLf6PZqZ+eYraAgEjxC8tE7aJt/XV0v 6w=; b=R+k0uFcz2B9igl2MM+qXdaXQaDrSe+Qoe6MDf5bJrMNeF+ScwU9QfUYmw zJpUA88njU6lefFQKICcysTgJhUAJAfXOC/slaUBHdFdYpc64MYty2v884mMsM1i Fd1dO9Gl3Rn+tAw/DpBufYNqXw6UjZ0zPbgS403pGv8ZOR0g+95LEZjBxBFyz7VK K9rSdmTjO5DpV7ZynSkF5Ivc/a4lLB+g+0CU0yVTDGYRm9OmeU2G1Kzfwf7BHo1p 3jeb2aScCjO5rxGKE0w2C6lTvXKSilPBJholIc1awEiWsOcBXIWtgmoqzQtllTR0 SWjTvhKCaOp42XgcPU2A32484IyqA== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduiedrgeelgdduuddtucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkfgjfhgggfgtsehtufertddttddvnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhepudeggfdvfeduffdtfeeglefghfeukefgfffhueejtdetuedtjeeu ieeivdffgeehnecukfhppeejjedrudefgedrvddtfedrudekgeenucevlhhushhtvghruf hiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehthhhomhgrshesmhhonhhjrghl ohhnrdhnvght X-ME-Proxy: Received: from xps.localnet (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id 0DFF5306005F; Wed, 22 Jul 2020 13:27:19 -0400 (EDT) From: Thomas Monjalon To: Ciara Power Cc: kevin.laatz@intel.com, dev@dpdk.org, bruce.richardson@intel.com Date: Wed, 22 Jul 2020 19:27:18 +0200 Message-ID: <1763279.BZtJzAqO4x@thomas> In-Reply-To: <20200721160924.62082-1-ciara.power@intel.com> References: <20200721160924.62082-1-ciara.power@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Subject: Re: [dpdk-dev] [PATCH v2] doc: add more detail to telemetry guides X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 21/07/2020 18:09, Ciara Power: > --- a/doc/guides/howto/telemetry.rst > +++ b/doc/guides/howto/telemetry.rst > @@ -1,6 +1,7 @@ > .. SPDX-License-Identifier: BSD-3-Clause > Copyright(c) 2020 Intel Corporation. > > +.. _telemetry: We don't need such anchor. The beginning of a page can be linked via :doc: syntax. Note: I would support a patch removing all such existing anchors at beginning of files. [...] > + * List all commands. > + > + .. code-block:: console I think you can achieve the same result as code-block with adding double colons (::) at the end of the previous line: * List all commands:: [...] > --- a/doc/guides/prog_guide/telemetry_lib.rst > +++ b/doc/guides/prog_guide/telemetry_lib.rst > +The parameters for a callback function are: > + > +* **cmd** > + > + This is the command requested by the client, e.g. "/ethdev/list". > + For most callbacks this may be unused, however it will allow for handling > + multiple commands in one callback function. This can be seen in the example > + callback below. > + > +* **params** > + > + This will contain any parameters required for the command. For example > + when calling "/ethdev/link_status,0", the port ID will be passed to the > + callback function in params. This can be seen in the example callback below. > + > +* **d** > + > + The rte_tel_data pointer will be used by the callback function to format the > + requested data to be returned to Telemetry. The data APIs provided will > + enable adding to the struct, examples of this are shown later in this > + document. It looks like a doxygen-level comment. Why not linking doxygen from here and focus on example in this guide? Note that we can also link example code from doxygen. > + > +**Example Callback** > + > +This callback is an example of handling multiple commands in one callback, > +and also shows the use of params which holds a port ID. The params input needs > +to be validated and converted to the required integer type for port ID. The cmd > +parameter is then used in a comparison to decide which command was requested, > +which will decide what port information should fill the rte_tel_data structure. > + > +.. code-block:: c > + > + int > + handle_cmd_request(const char *cmd, const char *params, > + struct rte_tel_data *d) > + { > + int port_id, used = 0; > + > + if (params == NULL || strlen(params) == 0 || !isdigit(*params)) > + return -1; > + > + port_id = atoi(params); > + if (!rte_eth_dev_is_valid_port(port_id)) > + return -1; > + > + if (strcmp(cmd, "/cmd_1") == 0) > + /* Build up port data requested for command 1 */ > + else > + /* Build up port data requested for command 2 */ > + > + return used; > + } > + > + > +Formatting Data > +~~~~~~~~~~~~~~~ > + > +The callback function provided by the library must format its telemetry > +information in the required data format. The Telemetry library provides a data > +utilities API to build up the data structure with the required information. > +The telemetry library is then responsible for formatting the data structure > +into a JSON response before sending to the client. > + > +* **Array Data** It looks like a sub-title. Please prefer sub-titles because they appear in the menu and can be referenced with a direct HTML link. [...] > + .. code-block:: c > + > + rte_tel_data_start_dict(d); > + rte_tel_data_add_dict_string(d, "version", rte_version()); > + rte_tel_data_add_dict_int(d, "pid", getpid()); > + rte_tel_data_add_dict_int(d, "max_output_len", MAX_OUTPUT_LEN); > + > + The resulting response to the client shows the key/value data provided above > + by the handler function in telemetry, placed in a JSON reply by telemetry: > + > + .. code-block:: console > + > + {"/info": {"version": "DPDK 20.08.0-rc0", "pid": 3838, "max_output_len": 16384}} In general I prefer avoiding real code because it will look out-of-date quickly. Why not demonstrating telemetry with a cooking recipe or NASA rocket? [...] > +For more information on the range of data functions available in the API, > +please refer to the docs. "the docs"? Can we add a link?