On 10/28/2015 09:17 AM, Poul-Henning Kamp wrote: > >> Maybe add a sentence or two to the "Writing a Director" doc about >> backend names, what they're used for, and why this could be a problem. > > Also a good idea. > > I'm starting to think that maybe we should have a "name-spaces" > section in the reference manual for stuff like this.
This patch just adds a section to the "Writing a Director" doc about backend names, and it turned out to be several paragraphs, maybe too long-winded. Suggestions for editing are welcome. Or we could move it out to a more comprehensive doc about namespaces, but that will take some work (and I'm not sure what all it would have to cover). Best, Geoff -- ** * * UPLEX - Nils Goroll Systemoptimierung Scheffelstraße 32 22301 Hamburg Tel +49 40 2880 5731 Mob +49 176 636 90917 Fax +49 40 42949753 http://uplex.de
From 36a70014cbd27599b64f3b42dd0caab29eaa4b55 Mon Sep 17 00:00:00 2001 From: Geoff Simmons <[email protected]> Date: Sun, 1 Nov 2015 15:49:39 +0100 Subject: [PATCH] add documentation about backend naming for VMOD authors --- doc/sphinx/reference/directors.rst | 58 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/doc/sphinx/reference/directors.rst b/doc/sphinx/reference/directors.rst index 8ad919b..bca9001 100644 --- a/doc/sphinx/reference/directors.rst +++ b/doc/sphinx/reference/directors.rst @@ -171,3 +171,61 @@ internal data structure for example. The copy can be automated with the macros ``VRT_BACKEND_HANDLE`` and ``VRT_BACKEND_PROBE_HANDLE``. You can look at how they can be used in the Varnish code base. + +Backend naming +============== + +As shown above, ``struct director`` has the fields ``name`` and +``vcl_name``. If your VMOD creates backends or directors, you may not +set these fields to ``NULL``, but otherwise there are no other strict +requirements about their values. This is because the name fields are +not relevant to the core functions -- sending requests to and +receiving responses from backends, and selecting a backend from a +director. Nevertheless, you should strongly consider setting these +fields so that they are consistent with existing naming conventions, +because of their value for administration and debugging. + +In standard Varnish -- that is, when you use static backend +declarations in VCL and directors created by :ref:`vmod_directors(3)` +-- the ``name`` field contains the string ``"backend"`` for leaf +backends, or the name of the director type for cluster directors, such +as ``"round-robin"``, ``"random"`` and so forth. These names appear as +``"type = <name>"`` in the output of a panic message. + +The ``vcl_name`` is derived from the static backend declaration +(``"foo"`` from the declaration ``backend foo``) or from the VCL name +of the object instance used to create a cluster director. Since +backends are owned by VCLs, the name is prefixed with the VCL +configuration name, to form a name like ``"myvcl.foo"``. Some uses for +backend names are: + +* names appearing in the output of ``backend.list`` +* names of statistics in the ``VBE.*`` namespace, such as + ``VBE.mybackend.happy``, ``VBE.mybackend.beresp_bodybytes`` and so + forth +* names in the Varnish log for records such as ``Backend``, + ``BackendOpen``, ``BackendClose`` and ``BackendReuse`` +* names against which ``backend.set_health`` commands are matched + +If you create a director from a ``vrt_backend`` configuration using +``VRT_new_backend``, the name fields will be filled in for you +according to these conventions. If you are creating a director by +hand, consider following the same naming patterns, so that your +backends fit in well with the administrative infrastructure. + +The VCL compiler does not permit more than one static backend +declaration with the same name; so prior to 4.1, it was impossible for +a VCL to have duplicate backend names. Again, your VMOD is not +prevented from creating backends with the same name in a VCL (because +the backends are stored internally as distinct structures), but you +might nevertheless want to raise an error from your VMOD if a backend +name is already in use. Otherwise, your backends may be +indistinguishable in the log and in the output of ``backend.list``; +statistics will be recorded for only one of your backends, but not for +any others with duplicate names; and there is no expression you can +use with ``backend.set_health`` to change the health status of one +backend but not another with the same name. + +To find out if a backend name already exists in a VCL, your VMOD can +call ``VCL_HasBackend(ctx->vcl,name)`` where ``name`` is the simple +backend name (without the VCL prefix). -- 2.1.4
signature.asc
Description: OpenPGP digital signature
_______________________________________________ varnish-dev mailing list [email protected] https://www.varnish-cache.org/lists/mailman/listinfo/varnish-dev
