Hello, Oops, correction needed to my post here.
In guideline number 6, IBM should not be contacted. Sorry about that. Guideline number 6 should say: When an operation fails due to a Wink internal error, Wink should log a clear, concise message to the end user detailing that the problem is an internal Wink error. Thanks, Carlton Carlton Mason IBM Websphere internet: [email protected] From: Carlton K Mason/Austin/IBM To: [email protected] Date: 06/11/2009 01:23 PM Subject: RE: Wink Project Guidelines Hello Everyone, I've been following this particular thread of conversation around logging with some interest as "serviceability" of Wink code is important. Serviceability is one dimension of code quality that measures the degree of ease (or difficulty) at problem determination and repair. Appropriate Logging at the right time, place, and level (debug vs error vs warn vs informational, etc..) is the primary mechanism available to make the Wink code serviceable. I would like to offer up some goals and guidelines around serviceability and logging for the community to discuss and consider. Some of which have already been mentioned in this thread of discussion. Here we go. Goals: 1. Ideally, for most problems, users should be able to detect, diagnose, and recover from Wink failures or Wink application failures WITHOUT requiring access to Wink source code or Wink developers. By Users, I mean both application developers building solutions with Wink but more so, the administrators or operations people who are responsible for ensuring solutions deployed and built on Wink can be serviced and kept running. This implies that certain persistent messages be logged without having to turn something on to make that happen. It also implies these type of messages should be translatable into another language as administrators/deployers/operations type roles may be located in many different countries and speak different languages. 2. Reduce the total cost of ownership and support cost for solutions built with Wink by reducing system or application down time by enabling rapid problem determination. This is achieved by careful logging of the right type (error vs warn vs info vs debug) and minimizing the need to enable debug trace and reproduce the problem. I know this is not always possible. There will be certain conditions that just could not be anticipated and stuff happens. 3. Wink run time must correctly determine at run time when a failure occurs and must isolate that failure to a specific internal component, external package or user action. Guidelines: 1. End user visible messages should be enabled for translation. Debug trace does not need to be enabled for translation. 2. When an operation fails due to a problem in the user application code, Wink, where possible, should log a clear, concise message to the end user that states that the problem is in application code. The message should explain as much as possible what condition was detected and why this is an error. From this information the user should be able to diagnose and solve the problem without requiring help, or enabling debug trace if possible. 3. When an operation fails due to a configuration error, Wink should log a clear concise message to the end user identifying which configuration setting is affected and why the current setting is in error. From this information the user should be able to solve the configuration problem without requiring help. 4. When an operation fails due to a network error or similar environmental error (operating system for instance), Wink should log a clear, concise message to the end user describing the network error and possible causes for it. From this information the user should be able to determine where to start network problem determination. 5. When an operation fails due to a problem with a non-Wink software package (e.g. database) Wink should log a clear concise message to the end user identifying which operation Wink was attempting to perform, the target of that operation and any error information returned from the non-Wink software package. 6. When an operation fails due to a Wink internal error, Wink should log a clear, concise message to the end user detailing that the problem is an internal Wink error and that IBM support should be contacted. The Wink run time should also gather as much information about that failure as possible. This information should allow a developer to diagnose the cause of the problem from the gathered information without requiring the customer to recreate the failure to gather additional information. 7. When an important state change has occurred that the end user may need to be aware of, Wink should log an informational message. For example, a certain resource is available or unavailable, a certain boot/start or stop point has been reached, or an important configuration change has been made. These are not error conditions but are important visible clues that aid in problem determination when things do go wrong. 8. When an important condition is encountered that, if not dealt with, will cause a failure, performance degradation, or other poor result a clear warning message should be logged that provides enough information for the end user to correct or take action. For example, running out of disk space or nearing the capacity limit for something. Regards, Carlton Carlton Mason IBM WebSphere internet: [email protected] From: Jesse A Ramos/Austin/i...@ibmus To: [email protected] Date: 06/11/2009 08:55 AM Subject: RE: Wink Project Guidelines I think Bryant and Mike are thinking of "users" to mean all users of the runtime which includes both application developers and users of those applications. In this sense, "developer" would refer more to the runtime developers, and not application developers. Although we likely won't be returning messages to users of applications (it was pointed out that WebApplicationException does not accept messages), I think it would be helpful to application developers who may wish to do their own debugging, as Mike mentioned, to have messages exposed to them be translated. - Jesse "Baram, Eliezer" <[email protected]> 06/11/2009 08:24 AM Please respond to [email protected] To "[email protected]" <[email protected]> cc Subject RE: Wink Project Guidelines My rule of thumb regarding message translating is: messages that are aimed for users should be translated and message that are aimed for developers should not be translated. Does this rule of thumb seems valid to you? I do not think that the REST framework generate messages that are aimed to the end users, even the warning that the JAX-RS spec suggests are aimed to the application developer that uses the framework and not to the user of the application. -----Original Message----- From: Bryant Luk [mailto:[email protected]] Sent: Thursday, June 11, 2009 3:59 PM To: [email protected] Subject: Re: Wink Project Guidelines I was thinking more about the log.warn() messages in this respect too. There are a few places (mainly in the application configuration) where the JAX-RS spec suggests issuing warnings. It would be nice that if a translation were available, that it be used in those default customer facing messages. I'm fairly certain we would have some debug information in those areas which would not be translated. On Thu, Jun 11, 2009 at 7:15 AM, Michael Rheinheimer<[email protected]> wrote: > Hi Michael, > > From working on the IBM code base, I think Bryant means that strings passed > through log.error would be externalized (for NLS), but messages passed > through log.debug would not be. I guess it depends on the logging mechanism > whether log.error is a "message that can be returned to the user" or not. I > would expect log.error to be configured to go to an error log, or even > System.err if that's appropriate for the given runtime environment. I think > the intent for log.error in the IBM runtime was to report user errors, not > JAX-RS engine data dumps -- that would be reserved for log.debug. The > log.error messages are intended to help the customer solve an issue > him/herself, such as if an important annotation has been forgotten (see > org.apache.cxf.jaxrs.utils.JAXRSUtils.findTargetMethod where the log.error > reports that a resource has no GET, POST, PUT, or DELETE annotations, for > example). So with that in mind, I would want log.error messages to be > readable by the customer in their language of choice. > > However, you make a good point that this means the log.error messages are > perhaps in a language unknown by the support team, but the log.debug > messages would be. So, what's the solution to this? Do we: > > 1) do not externalize anything that goes through log.*, thus externalizing > only the messages in a thrown exception or message response body? or > 2) use log.debug and log.error side-by-side every place a log.error message > might appear so we can report in both a customer's language and English? (I > don't like this option) > 3) others? > > Ideally, I think log.error would be used to report NLS strings so a customer > can quickly resolve the error him/herself without requiring a call to > support. > > Your thoughts? > > > Mike Rheinheimer > (512) 838-0086 t/l 678-0086 > WebSphere WebService Core Engine Team > > > "Elman, Michael" ---06/11/2009 02:58:57 AM---Well, I'm not quite sure that > logging messages should be externalized. I mean here the messages that > > > From: > "Elman, Michael" <[email protected]> > To: > "[email protected]" <[email protected]> > Date: > 06/11/2009 02:58 AM > Subject: > RE: Wink Project Guidelines > ________________________________ > > > Well, I'm not quite sure that logging messages should be externalized. I > mean here the messages that are only written to log files. It may happen > that a problem will occur on the customer site and we'll ask for the logs. > I'm quite unsure that I want to read messages in a language I don't know. > > I think that only messages that can be returned to the user must be > externalized. In case of Wink, these can be messages thrown in exceptions or > put in the response body. > > Btw, there is almost no way to throw exceptions with a message that can be > returned to the user from the JAX-RS runtime. WebApplicationException that > should be thrown in most cases, has no constructors that accept messages. > And I don't think that throwing a RuntimeException with a message embedded > in the WebApplicationException is a good solution: the stacktrace looks > weird; and actually the message will not be returned to the client, since > the default handling of WebApplicationException ignores the message. > > Michael Elman > > > -----Original Message----- > From: Bryant Luk [mailto:[email protected]] > Sent: Wednesday, June 10, 2009 5:21 PM > To: [email protected] > Subject: Re: Wink Project Guidelines > > One quick note, I added an explicit part for logging messages. > Basically I think we should externalize any logging message strings > into a message.properties file that are not debug messages (for NLS > and the like). > > On Tue, Jun 9, 2009 at 9:26 AM, Bryant Luk<[email protected]> wrote: >> I like the coding guidelines. I think using Maven would be good. The >> only issue I think we need to address is making sure that we allow the >> integration tests to run on various platforms.(jetty, tomcat, >> geronimo, etc.), maybe via the Maven profiles functionality. >> >> On Mon, Jun 8, 2009 at 8:50 AM, Elman, Michael<[email protected]> wrote: >>> I've created "Coding Guidelines" under the "Project Guidelines". >>> Feel free to modify/add/discuss. >>> >>> Michael Elman >>> >>> >>> -----Original Message----- >>> From: Bryant Luk [mailto:[email protected]] >>> Sent: Friday, June 05, 2009 6:10 AM >>> To: [email protected] >>> Subject: Re: Wink Project Guidelines >>> >>> >>> I've updated the Wink Wiki with some of the project guidelines at: >>> >>> http://cwiki.apache.org/confluence/display/WINK/Project+Guidelines >>> >>> I copied what I thought was relevant for now. Feel free to >>> modify/add/discuss. >>> >>> Thanks, >>> >>> Bryant Luk >>> [email protected] >>> >>> >>> Davanum Srinivas <[email protected]> wrote on 06/04/2009 08:25:09 PM: >>> >>>> [image removed] >>>> >>>> Re: Wink Project Guidelines >>>> >>>> Davanum Srinivas >>>> >>>> to: >>>> >>>> wink-dev >>>> >>>> 06/04/2009 08:26 PM >>>> >>>> Please respond to wink-dev >>>> >>>> Eli, Bryant, >>>> >>>> Feel free to use the wiki: >>>> http://cwiki.apache.org/confluence/display/WINK/Index >>>> >>>> thanks, >>>> dims >>>> >>>> On Thu, Jun 4, 2009 at 8:39 AM, Baram, Eliezer<[email protected]> wrote: >>>> > Hi >>>> > I think it can be a starting point, there are some modifications I >>>> believe we should add, but in general it look good. >>>> > let's copy it as a draft and then do the modifications and >>>> discussions upon it. >>>> > Regards, >>>> > Eli >>>> > >>>> > >>>> > >>>> > >>>> > -----Original Message----- >>>> > From: Bryant Luk [mailto:[email protected]] >>>> > Sent: Wednesday, June 03, 2009 11:39 PM >>>> > To: [email protected] >>>> > Subject: Wink Project Guidelines >>>> > >>>> > >>>> > Hi all, >>>> > >>>> > For project guidelines, Jakarta seems to have a well written set >>> (thanks >>>> > Carlton): >>>> > >>>> > http://jakarta.apache.org/site/guidelines.html >>>> > >>>> > Any thoughts if we should just copy these guidelines for Wink? Some >>>> > of >>>> > these aren't applicable but these seem fairly standard in how other >>> Apache >>>> > projects are run. >>>> > >>>> > I imagine that more coding guidelines would need to be done later >>>> > (like >>>> > maybe formatting, logging, NLS, etc.) >>>> > >>>> > Thanks, >>>> > >>>> > Bryant Luk >>>> > [email protected] >>>> > >>>> >>>> >>>> >>>> -- >>>> Davanum Srinivas :: http://davanum.wordpress.com >>> >> >> >> >> -- >> >> - Bryant Luk >> > > > > -- > > - Bryant Luk > > > -- - Bryant Luk
