Abbie,
Here is my comments on the latest Communication draft,
draft-ietf-opes-end-comm-02.
The overall structure and flow of the document improved
significantly. Thank you!
There are several major flaws and few minor bugs remaining. In
this email, I will try to concentrate on major flaws:
* Compliance subjects: The number of things for which
there is at least one MUST/SHOULD/MAY requirement, is
too large. Sometimes it is even not clear what subject
a requirement applies to. Please make sure that all
requirements apply to an OPES entity, an OPES system,
or a application binding specification. If you feel
that other compliance subjects are needed, let's
discuss this. Please add a "Compliance Considerations"
section.
* Misplaced compliance requirements: Please avoid
sprinkling informative text and definitions(!) with
MUST/SHOULD/MAYs. Let's try to move all requirements
for OPES entities to the corresponding sections of
the draft.
* Multiple definitions: Several concepts have multiple
definitions. There must be one definition, optionally
followed by examples and rationale.
* Vague requirements: Please check that every
MUST/SHOULD/MAY uses no undefined or unnecessary
adjectives. If a particular requirement cannot be
formulated without a vague adjective, perhaps it should
not be a requirement. This may seem like a lot of work
but (a) it is an important spec quality aspect and
(b) you are likely to end up with fewer requirements
after the above flaws are addressed.
* Vague definitions: same as vague requirements but
as applied to definitions. Avoid adjectives and
implied clauses in a definition.
* Implied definitions: "Foo is Bar" is a definition.
"Foo can be Bar", "Foo describes Bar", etc. are not.
MUST/SHOULD/MAY keywords identify requirements.
You may want to use "Definition:" prefix to identify
definitions. If you do not like the prefix, please
make sure that all definition-looking sentences are
either clearly marked as definitions or rephrased
to avoid misleading looks.
* Bypass: the draft does not mention bypass mechanisms
but should.
Below, I will point to specific places exhibiting the above flaws.
Your original text is quoted using "> ". I will use flaw headings from
the above list to shorten notes when possible.
This memo documents tracing requirements for Open Pluggable Edge
Services (OPES).
Bypass.
The execution of such services is governed by a set of rules
installed on the OPES processor. ...
The above paragraph seem to have very little to do with tracing.
Do we need to repeat architecture description here?
The work specify the requirements for providing tracing functionality
for the OPES architecture [8]. This document specifies tracing
mechanisms that the OPES architecture could provide that enable data
provider application to detect inappropriate client centric actions
by OPES entities.
So which is it? "Requirements for providing tracing functionality"
or "tracing mechanisms"?
This document specifies tracing
mechanisms that the OPES architecture could provide that enable data
provider application to detect inappropriate client centric actions
by OPES entities.
What about inappropriate server-centric actions? Are tracing
mechanisms symmetric?
This work investigates this possibility and discusses possible
methods that could be used to detect faulty OPES processors or
callout servers by end points in an OPES flow.
Let's be more firm/specific: "This document specifies ... for ..."
Avoid "possibilities", "investigations", and "coulds".
The document is organized as follows: Section 2 defines OPES Domain
...
Delete the above paragraph. It is an [incorrect] repetition of the
table of contents. This is not a research paper without a TOC where
such paragraphs are common and useful.
This sections clarifies the terms OPES system and OPES Domain [8].
[8], the Architecture draft you are referring to does not define OPES
system and OPES Domain. Are you implying that the Architecture draft
should be fixed to include such definitions? If yes, please place an
XXX note so that we do not forget to change the Architecture draft and
remove system/domain definitions from Communications draft when the
Architecture draft is updated. If you are not implying anything, then
please remove the above reference to [8].
An OPES domain describes the collection of OPES entities that a
single provider operates.
Implied definition?
An OPES domain is ...
I failed to find much text that actually uses OPES Domain. I can only
see two requirements (and I do not understand their rationale). If
those requirements are gone, I would suggest removing OPES Domain
until is needed. (OPES Domain is different from OPES trust domain,
right?).
An OPES domain describes the collection of OPES entities that a
single provider operates.
Please give an example. It is not clear what "single provider
operates" means because it is not clear what is a "provider" in this
context and what it means to "operate" an OPES entity.
OPES domains can be based on trust or other operational boundaries.
Is "trust" an operational boundary? What is an "operational boundary"?
All entities of an "OPES Domain" MUST be in the same trust domain.
Compliance subjects. Does not your OPES Domain definition above
imply the "same trust domain" clause?
An OPES system consists of a limited set of OPES entities, parts of a
single or of multiple OPES domains, organized by (or on behalf) of
either a data provider application or a data consumer application to
perform authorized services on a given application message.
Vague definition.
An OPES system can be formed in a recursive manner. An OPES system
can start ...
Implied definition? Multiple definitions for OPES system?
Each OPES entity in an OPES system MUST be directly addressable at
the IP level by a data consumer application.
Misplaced compliance requirement. Also, is this requirement really in
Communications draft scope?
An OPES domain MUST not be an OPES sub-system.
Compliance subject.
Also, what is an OPES sub-system? A subset of OPES entities within an
OPES System? If yes, then does not Figure 1 show OPES domains that are
OPES sub-systems?
An OPES domain MUST
require external resources to provide services.
Compliance subject. Or is it a part of an implied definition?
A data consumer
application MUST be able to receive tracing information on per
message basis
Compliance subject.
Tracing is defined as the inclusion of
necessary information within a message in an OPES flow that could be
and
o OPES tracing: the process of including, manipulating, and
interpreting an OPES trace in an OPES System.
Multiple definitions.
To emphasize, the above definition means that OPES tracing SHOULD be
performed on per message basis.
Compliance subject.
In an OPES System the task of providing tracing information, must
take into account the following considerations:
Assuming the above "must" is a "MUST", this is a Compliance subject
flaw. The subject of the above must is the "task of providing tracing
information"!
Tracing information MUST be able to provide a data consumer
application with useful information without tracing the exact OPES
Processor or callout servers that adapted the data.
Compliance subject. Vague requirement.
o An OPES service SHOULD add its entry to the trace.
I believe this should be a MAY. Rationale: Many OPES services are
message-agnostic and operate on message content or parts. Such
services cannot manipulate message headers and, hence, cannot trace
themselves. Since an ideal OPES service is usually message-agnostic,
it seems inappropriate to place a SHOULD-level requirement that an
ideal implementation would necessarily violate.
For example, an OPES processor may add or
remove callout service entries in order to manage the size of a
trace.
Consider making this a separate paragraph, with an appropriate intro
phrase. Let's not clobber the requirements list.
trace. Other considerations include:
Is this still a part of a "For example" clause?
* The OPES processor MAY have a fixed configuration that enable
it to respond to tracing inquires.
Unclear. Needs more details/examples? Is this (and others in the same
list) an example or a MAY-level requirement? They look like examples
to me. "A proxy MAY cache" is a requirement. "A proxy can keep its
cache in RAM" is an example or similar informative text. In our scope,
if something does not effect traffic on the wire, it is most likely
NOT a requirement.
From an OPES context, a good tracing approach is similar to a trouble
ticket ready for submission to a known address.
The trouble ticket analogy is good. Please rephrase so that it is
clear that the "known address" is _included_ in (a part of) the
"ticket" in our case.
3.2 Requirements for Information Related to Traceable Entities?
Is question mark at the end intentional?
Compliance subject.
The requirements for information as related to entities that are
traceable in an OPES flow are:
Compliance subject.
What level (MUST/SHOULD/MAY) are these requirements.
the concept of an "OPES system"
being traceable, requires that each OPES processor MUST support
tracing.
The concept most certainly does not require that.
An OPES provider can have its private policy for trace information,
but it MUST support tracing mechanisms and it MUST reveal its
policy.
Compliance subject.
o Each OPES processor MUST belong to a single OPES Domain.
o Each OPES processor MUST have a Unique Identity in that Domain.
Why?
In an OPES system, it is the task of an OPES processor to add trace
records to application messages. In this case, the callout servers
that uses the OCP protocol [5] are not affected by tracing
requirements.
And yet, we say that callout servers SHOULD add trace records.
In order for an OCP protocol to be tracing neutral, an OPES
processor in an OPES system MUST be able to meet the following
requirements:
Why is Communication draft concerned with OCP protocol neutrality?
o Callout services adapt payload regardless of the application
protocol in use and leave header adjustment to OPES processor.
This is not a requirement.
o OPES processor SHOULD be able to trace it's own invocation and
service(s) execution since they understand the application
protocol.
Misplaced compliance requirement.
o Callout servers MAY be able to add their own OPES trace records
to application level messages.
Conflicts with an earlier SHOULD?
A trust domain may include several OPES systems.
By definition of an OPES system, it is not possible. OPES system
includes everybody that trusts somebody within that system.
Within a trust domain, there MUST be at least support for one trace
entry per OPES system.
Compliance subject.
Entities outside of that system may or may not see any traces,
depending on domain policies or configuration. For example, if an
OPES system is on the content provider "side", end-users are not
guaranteed any traces. If an OPES system is working inside end-user
domain, the origin server is not guaranteed any traces related to
user requests.
While I agree with the realism of the above statement, it goes against
IAB wishes, does it not? We already require on a MUST level that the
above does not happen.
In order to support tracing, the following aspects must be addressed:
...
Misplaced compliance requirements.
Compliance subjects.
(this applies pretty much to the whole section 7 as it repeats many
requirements and introduces many requirements for unclear or
inappropriate subjects)
8. Tracing Examples
Since all current examples are HTTP-specific, would it be better to
keep them in the HTTP Adaptation draft? Is it a good idea to repeat
more than one example from another draft?
If you keep the examples, please update 1995 dates used (see latest
HTTP adaptation draft or use any recent date of your choice).
9. Optional Notification
The text of this section repeats IAB draft rant. Should we keep the
rant in IAB draft and just leave one short paragraph with a single
example from the HTTP Adaptation draft?
HTH,
Alex.