mirror of
https://github.com/openvswitch/ovs
synced 2025-08-22 09:58:01 +00:00
939a5cea5b
For monitoring systems such as Prometheus it would be beneficial if
OVS would expose statistics in a machine-readable format.
This patch introduces support for different output formats to
ovs-appctl. It gains a global option '-f,--format' which changes it to
print a JSON document instead of plain-text for humans. For example, a
later patch implements support for
'ovs-appctl --format json dpif/show'. By default, the output format
is plain-text as before.
A new 'set-options' command has been added to lib/unixctl.c which
allows to change the output format of the commands executed afterwards
on the same socket connection. It is supposed to be run by ovs-appctl
transparently for the user when a specific output format has been
requested.
For example, when a user calls 'ovs-appctl --format json dpif/show',
then ovs-appctl will call 'set-options' to set the output format as
requested by the user and afterwards it will call the actual command
'dpif/show'.
This ovs-appctl behaviour has been implemented in a backward compatible
way. One can use an updated client (ovs-appctl) with an old server
(ovs-vswitchd) and vice versa. Of course, JSON output only works when
both sides have been updated.
Two access functions unixctl_command_{get,set}_output_format() and a
unixctl_command_reply_json function have been added to lib/unixctl.h:
unixctl_command_get_output_format() is supposed to be used in commands
like 'dpif/show' to query the requested output format. When JSON output
has been selected, the unixctl_command_reply_json() function can be
used to return JSON objects to the client (ovs-appctl) instead of
plain-text with the unixctl_command_reply{,_error}() functions.
When JSON has been requested but a command has not implemented JSON
output the plain-text output will be wrapped in a provisional JSON
document with the following structure:
{"reply":"$PLAIN_TEXT_HERE","reply-format":"plain"}
Thus commands which have been executed successfully will not fail when
they try to render the output at a later stage.
A test for the 'version' command has been implemented which shows how
the provisional JSON document looks like in practice. For a cleaner
JSON document, the trailing newline has been moved from the program
version string to function ovs_print_version(). This way, the
plain-text output of the 'version' command has not changed.
Output formatting has been moved from unixctl_client_transact() in
lib/unixctl.c to utilities/ovs-appctl.c. The former merely returns the
JSON objects returned from the server and the latter is now responsible
for printing it properly.
In popular tools like kubectl the option for output control is usually
called '-o|--output' instead of '-f,--format'. But ovs-appctl already
has an short option '-o' which prints the available ovs-appctl options
('--option'). The now chosen name also better aligns with ovsdb-client
where '-f,--format' controls output formatting.
Reported-at: https://bugzilla.redhat.com/1824861
Signed-off-by: Jakob Meng <code@jakobmeng.de>
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
71 lines
2.4 KiB
C
71 lines
2.4 KiB
C
/*
|
|
* Copyright (c) 2008, 2009, 2011 Nicira, Inc.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at:
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#ifndef UNIXCTL_H
|
|
#define UNIXCTL_H 1
|
|
|
|
#include <stdbool.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
struct json;
|
|
enum unixctl_output_fmt {
|
|
UNIXCTL_OUTPUT_FMT_TEXT = 1 << 0,
|
|
UNIXCTL_OUTPUT_FMT_JSON = 1 << 1,
|
|
};
|
|
|
|
const char *unixctl_output_fmt_to_string(enum unixctl_output_fmt);
|
|
bool unixctl_output_fmt_from_string(const char *, enum unixctl_output_fmt *);
|
|
|
|
/* Server for Unix domain socket control connection. */
|
|
struct unixctl_server;
|
|
int unixctl_server_create(const char *path, struct unixctl_server **);
|
|
void unixctl_server_run(struct unixctl_server *);
|
|
void unixctl_server_wait(struct unixctl_server *);
|
|
void unixctl_server_destroy(struct unixctl_server *);
|
|
|
|
const char *unixctl_server_get_path(const struct unixctl_server *);
|
|
|
|
/* Client for Unix domain socket control connection. */
|
|
struct jsonrpc;
|
|
int unixctl_client_create(const char *path, struct jsonrpc **client);
|
|
int unixctl_client_transact(struct jsonrpc *client,
|
|
const char *command,
|
|
int argc, char *argv[],
|
|
struct json **result, struct json **error);
|
|
|
|
/* Command registration. */
|
|
struct unixctl_conn;
|
|
typedef void unixctl_cb_func(struct unixctl_conn *,
|
|
int argc, const char *argv[], void *aux);
|
|
void unixctl_command_register(const char *name, const char *usage,
|
|
int min_args, int max_args,
|
|
unixctl_cb_func *cb, void *aux);
|
|
enum unixctl_output_fmt unixctl_command_get_output_format(
|
|
struct unixctl_conn *);
|
|
void unixctl_command_reply_error(struct unixctl_conn *, const char *error);
|
|
void unixctl_command_reply(struct unixctl_conn *, const char *body);
|
|
void unixctl_command_reply_json(struct unixctl_conn *,
|
|
struct json *body);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* unixctl.h */
|